Documentación de la API web de ASP.NET Core con Swagger/OpenAPIASP.NET Core web API documentation with Swagger / OpenAPI

Por Christoph Nienaber y Rico SuterBy Christoph Nienaber and Rico Suter

Swagger (OpenAPI) es una especificación independiente del lenguaje que sirve para describir API REST.Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. Permite a los equipos y a los usuarios comprender las capacidades de una API REST sin acceso directo al código fuente.It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Sus principales objetivos son los siguientes:Its main goals are to:

  • Minimizar la cantidad de trabajo necesaria para conectar los servicios desacoplados.Minimize the amount of work needed to connect decoupled services.
  • Reducir la cantidad de tiempo necesario para documentar un servicio con precisión.Reduce the amount of time needed to accurately document a service.

Las dos implementaciones principales de OpenAPI para .NET son Swashbuckle y NSwag, consulte:The two main OpenAPI implementations for .NET are Swashbuckle and NSwag, see:

OpenApi y SwaggerOpenApi vs. Swagger

El proyecto de Swagger se donó a la iniciativa OpenAPI en 2015 y desde entonces se conoce como OpenAPI.The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. Ambos nombres se usan indistintamente.Both names are used interchangeably. Sin embargo, "OpenAPI" hace referencia a la especificación.However, "OpenAPI" refers to the specification. "Swagger" hace referencia a la familia de productos comerciales y de código abierto de Smartbear que funcionan con la especificación OpenAPI."Swagger" refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. Los siguientes productos de código abierto, como OpenAPIGenerator, también se encuentran bajo el nombre de la familia de Swagger, a pesar de no ser publicados por Smartbear.Subsequent open-source products, such as OpenAPIGenerator, also fall under the Swagger family name, despite not being released by SmartBear.

En resumen:In short:

  • OpenAPI es una especificación.OpenAPI is a specification.
  • Swagger es una herramienta que usa la especificación OpenAPI.Swagger is tooling that uses the OpenAPI specification. Por ejemplo, OpenAPIGenerator y SwaggerUI.For example, OpenAPIGenerator and SwaggerUI.

Especificación de OpenAPI (OpenAPI. JSON)OpenAPI specification (openapi.json)

La especificación OpenAPI es un documento que describe las capacidades de la API.The OpenAPI specification is a document that describes the capabilities of your API. El documento se basa en las anotaciones de atributos y XML dentro de los controladores y modelos.The document is based on the XML and attribute annotations within the controllers and models. Es la parte principal del flujo OpenAPI y se usa para impulsar herramientas como SwaggerUI.It's the core part of the OpenAPI flow and is used to drive tooling such as SwaggerUI. De forma predeterminada, se denomina openapi.json.By default, it's named openapi.json. Este es un ejemplo de especificación de OpenAPI (se ha reducido por motivos de brevedad):Here's an example of an OpenAPI specification, reduced for brevity:

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Interfaz de usuario de SwaggerSwagger UI

La interfaz de usuario de OpenAPI es una interfaz de usuario basada en Internet que proporciona información sobre el servicio por medio de la especificación de Swagger generada.Swagger UI offers a web-based UI that provides information about the service, using the generated OpenAPI specification. Swashbuckle y NSwag incluyen una versión insertada de la interfaz de usuario de Swagger, de modo que se puede hospedar en una aplicación ASP.NET Core realizando una llamada de registro de middleware.Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. La interfaz de usuario web tiene este aspecto:The web UI looks like this:

Interfaz de usuario de Swagger

Todos los métodos de acción públicos aplicados a los controladores se pueden probar desde la interfaz de usuario.Each public action method in your controllers can be tested from the UI. Seleccione un nombre de método para expandir la sección.Select a method name to expand the section. Agregue todos los parámetros necesarios y seleccione Try it out! (¡Pruébelo!).Add any necessary parameters, and select Try it out!.

Ejemplo de prueba de acción GET de Swagger

Nota

La versión de interfaz de usuario de Swagger usada para las capturas de pantalla es la versión 2.The Swagger UI version used for the screenshots is version 2. Para obtener un ejemplo de la versión 3, vea el ejemplo de Petstore.For a version 3 example, see Petstore example.

Pasos siguientesNext steps