Documentação da API Web ASP.NET Core com o Swagger/OpenAPI

Por Christoph Nienaber e Rico Suter

O Swagger (OpenAPI) é uma especificação independente de linguagem para descrever REST APIs. Ele permite que computadores e humanos entendam os recursos de uma REST API sem acesso direto ao código-fonte. Seus principais objetivos são:

  • Minimize a quantidade de trabalho necessária para conectar serviços separados.
  • Reduza o tempo necessário para documentar com precisão um serviço.

As duas principais implementações de OpenAPI para .NET são Swashbuckle e NSwag, consulte:

OpenAPI vs. Swagger

O projeto Swagger foi doado para a Iniciativa OpenAPI em 2015 e, desde então, foi chamado de OpenAPI. Ambos os nomes são usados de forma intercambiável. No entanto, "OpenAPI" refere-se à especificação . "Swagger" refere-se à família de produtos de software livre e comerciais do SmartBear que funcionam com a Especificação openAPI. Os produtos de software livre subsequentes, como OpenAPIGenerator, também se enquadram no nome da família Swagger, apesar de não terem sido lançados pelo SmartBear.

Resumindo:

  • OpenAPI é uma especificação.
  • O Swagger é uma ferramenta que usa a especificação OpenAPI. Por exemplo, OpenAPIGenerator e SwaggerUI.

Especificação de OpenAPI (openapi.json)

A especificação OpenAPI é um documento que descreve os recursos de sua API. O documento é baseado no XML e nas anotações de atributo dentro dos controladores e modelos. É a parte principal do fluxo OpenAPI e é usada para impulsionar ferramentas como SwaggerUI. Por padrão, ele é chamado openapi.jsonde . Aqui está um exemplo de uma especificação de OpenAPI, reduzida para fins de brevidade:

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

Swagger UI

A interface do usuário do Swagger oferece uma interface do usuário baseada na Web que fornece informações sobre o serviço, usando a especificação de OpenAPI gerada. O Swashbuckle e o NSwag incluem uma versão incorporada da interface do usuário do Swagger, para que ele possa ser hospedado em seu aplicativo ASP.NET Core usando uma chamada de registro de middleware. A interface do usuário da Web tem esta aparência:

Interface do usuário do Swagger

Todo método de ação pública nos controladores pode ser testado da interface do usuário. Selecione um nome de método para expandir a seção. Adicione os parâmetros necessários e selecione Experimentar!.

Teste GET de Swagger de exemplo

Observação

A versão da interface do usuário do Swagger usada para as capturas de tela é a versão 2. Para obter um exemplo da versão 3, confira Exemplo Petstore.

Próximas etapas