Páginas de ajuda da API Web ASP.NET Core com o Swagger/OpenAPIASP.NET Core web API help pages with Swagger / OpenAPI

Por Christoph Nienaber e Rico SuterBy Christoph Nienaber and Rico Suter

Ao consumir uma API Web, entender seus vários métodos pode ser um desafio para um desenvolvedor.When consuming a Web API, understanding its various methods can be challenging for a developer. O Swagger, também conhecido como OpenAPI, resolve o problema da geração de páginas de ajuda e de documentação úteis para APIs Web.Swagger, also known as OpenAPI, solves the problem of generating useful documentation and help pages for Web APIs. Ele oferece benefícios, como documentação interativa, geração de SDK de cliente e capacidade de descoberta de API.It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

Neste artigo, são exibidas as implementações do .NET do Swagger Swashbuckle.AspNetCore e NSwag:In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:

  • O Swashbuckle.AspNetCore é um projeto de software livre para geração de documentos do Swagger para APIs Web ASP.NET Core.Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

  • O NSwag é outro projeto de software livre para geração de documentos do Swagger e a integração da interface do usuário do Swagger ou do ReDoc em APIs Web ASP.NET Core.NSwag is another open source project for generating Swagger documents and integrating Swagger UI or ReDoc into ASP.NET Core web APIs. Além disso, o NSwag oferece abordagens para gerar o código de cliente C# e TypeScript para sua API.Additionally, NSwag offers approaches to generate C# and TypeScript client code for your API.

O que é o Swagger / OpenAPI?What is Swagger / OpenAPI?

O Swagger é uma especificação independente de linguagem para descrever APIs REST.Swagger is a language-agnostic specification for describing REST APIs. O projeto de Swagger foi doado para a Iniciativa OpenAPI, na qual agora é chamado de OpenAPI.The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as OpenAPI. Ambos os nomes são intercambiáveis, mas OpenAPI é o preferencial.Both names are used interchangeably; however, OpenAPI is preferred. Ele permite que computadores e pessoas entendam os recursos de um serviço sem nenhum acesso direto à implementação (código-fonte, acesso à rede, documentação).It allows both computers and humans to understand the capabilities of a service without any direct access to the implementation (source code, network access, documentation). Uma meta é minimizar a quantidade de trabalho necessário para conectar-se a serviços desassociados.One goal is to minimize the amount of work needed to connect disassociated services. Outra meta é reduzir o período de tempo necessário para documentar um serviço com precisão.Another goal is to reduce the amount of time needed to accurately document a service.

Especificação do Swagger (swagger.json)Swagger specification (swagger.json)

O ponto central para o fluxo do Swagger é a especificação do Swagger que é, por padrão, um documento chamado swagger.json.The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. Ele é gerado pela cadeia de ferramentas do Swagger (ou por implementações de terceiros) com base no seu serviço.It's generated by the Swagger tool chain (or third-party implementations of it) based on your service. Ele descreve os recursos da API e como acessá-lo com HTTP.It describes the capabilities of your API and how to access it with HTTP. Ele gera a interface do usuário do Swagger e é usado pela cadeia de ferramentas para habilitar a geração e a descoberta de código de cliente.It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. Aqui está um exemplo de uma especificação do Swagger, resumida:Here's an example of a Swagger specification, reduced for brevity:

{
   "swagger": "2.0",
   "info": {
       "version": "v1",
       "title": "API V1"
   },
   "basePath": "/",
   "paths": {
       "/api/Todo": {
           "get": {
               "tags": [
                   "Todo"
               ],
               "operationId": "ApiTodoGet",
               "consumes": [],
               "produces": [
                   "text/plain",
                   "application/json",
                   "text/json"
               ],
               "responses": {
                   "200": {
                       "description": "Success",
                       "schema": {
                           "type": "array",
                           "items": {
                               "$ref": "#/definitions/TodoItem"
                           }
                       }
                   }
                }
           },
           "post": {
               ...
           }
       },
       "/api/Todo/{id}": {
           "get": {
               ...
           },
           "put": {
               ...
           },
           "delete": {
               ...
   },
   "definitions": {
       "TodoItem": {
           "type": "object",
            "properties": {
                "id": {
                    "format": "int64",
                    "type": "integer"
                },
                "name": {
                    "type": "string"
                },
                "isComplete": {
                    "default": false,
                    "type": "boolean"
                }
            }
       }
   },
   "securityDefinitions": {}
}

Interface do usuário do SwaggerSwagger UI

A Interface do usuário do Swagger oferece uma interface do usuário baseada na Web que conta com informações sobre o serviço, usando a especificação do Swagger gerada.Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger specification. 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.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. A interface do usuário da Web tem esta aparência:The web UI looks like this:

Interface do usuário do Swagger

Todo método de ação pública nos controladores pode ser testado da interface do usuário.Each public action method in your controllers can be tested from the UI. Clique em um nome de método para expandir a seção.Click a method name to expand the section. Adicione os parâmetros necessários e, em seguida, clique em Experimente!.Add any necessary parameters, and click Try it out!.

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.The Swagger UI version used for the screenshots is version 2. Para obter um exemplo da versão 3, confira Exemplo Petstore.For a version 3 example, see Petstore example.

Próximas etapasNext steps