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

Por Christoph Nienaber y Rico Suter

Swagger (OpenAPI) es una especificación independiente del lenguaje que sirve para describir API REST. Permite a los equipos y a los usuarios comprender las capacidades de una API REST sin acceso directo al código fuente. Sus principales objetivos son los siguientes:

  • Minimizar la cantidad de trabajo necesaria para conectar los servicios desacoplados.
  • Reducir la cantidad de tiempo necesario para documentar un servicio con precisión.

Las dos implementaciones principales de OpenAPI para .NET son Swashbuckle y NSwag, consulte:

OpenApi y Swagger

El proyecto de Swagger se donó a la iniciativa OpenAPI en 2015 y desde entonces se conoce como OpenAPI. Ambos nombres se usan indistintamente. Sin embargo, "OpenAPI" hace referencia a la especificación. "Swagger" hace referencia a la familia de productos comerciales y de código abierto de Smartbear que funcionan con la especificación OpenAPI. 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.

En resumen:

  • OpenAPI es una especificación.
  • Swagger es una herramienta que usa la especificación OpenAPI. Por ejemplo, OpenAPIGenerator y SwaggerUI.

Especificación de OpenAPI (OpenAPI. JSON)

La especificación OpenAPI es un documento que describe las capacidades de la API. El documento se basa en las anotaciones de atributos y XML dentro de los controladores y modelos. Es la parte principal del flujo OpenAPI y se usa para impulsar herramientas como SwaggerUI. De forma predeterminada, se denomina openapi.json. Este es un ejemplo de especificación de OpenAPI (se ha reducido por motivos de brevedad):

{
  "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 Swagger

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. 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. La interfaz de usuario web tiene este aspecto:

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. Seleccione un nombre de método para expandir la sección. Agregue todos los parámetros necesarios y seleccione Try it out! (¡Pruébelo!).

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. Para obtener un ejemplo de la versión 3, vea el ejemplo de Petstore.

Pasos siguientes