Documentar uma API Web do ASP.NET Core com as ferramentas do Swagger

  • 5 minutos

Uma API pode ser muito importante, mas não ganhará impulso se os desenvolvedores não souberem como usá-la. Os desenvolvedores querem integrar uma API o mais rápido possível. Boa documentação de API ajuda um desenvolvedor a compreender as funcionalidades da API e como ele deve ser usada, tornando a integração mais eficiente.

Tradicionalmente, toda a documentação que descreve uma API e uso dela foi escrita à mão. Agora, temos uma especificação padrão para descrições de API chamada OpenAPI. O Swagger UI fornece implementação e ferramentas de teste da especificação OpenAPI para suas APIs. O Swashbuckle é um pacote de software livre que fornece a geração automática de documentos de descrição do OpenAPI diretamente de controladores de API Web usando a reflexão do .NET. O Swashbuckle ajuda a automatizar o processo de descrição, tornando mais fácil para as equipes gerar, manter e usar a documentação da API baseada em OpenAPI. Você descreve sua API e permite que ferramentas gerem documentação avançada.

O que é OpenAPI?

OpenAPI é uma especificação usada para descrever APIs REST. A OpenAPI é independente de linguagem e permite que você descreva sua API inteira, incluindo:

  • Pontos de extremidade disponíveis
  • Parâmetros de operação
  • Métodos de autenticação
  • Contato e outras informações

Você pode escrever especificações da API em JSON ou YAML. Com a especificação OpenAPI, seres humanos e computadores podem compreender as funcionalidades da sua API sem ter acesso ao seu código-fonte.

O que é o Swagger?

O Swagger é um conjunto de ferramentas open-source criadas em torno da especificação de OpenAPI. Essas ferramentas podem ajudar você a projetar, compilar e documentar APIs REST. O Swagger usa a especificação OpenAPI da sua API para entender a respectiva estrutura.

Por exemplo, o Swagger UI é uma ferramenta que pode renderizar visualmente a documentação em um navegador para uma API definida com a especificação de OpenAPI. O Swagger Codegen pode usar a mesma especificação de OpenAPI de uma API e gerar SDKs de cliente.

O que é o Swashbuckle?

O Swashbuckle é uma implementação open-source do Swagger usada para gerar documentação do Swagger para APIs do .NET Core usando a reflexão do .NET.

O Swashbuckle tem três componentes principais:

  • Swashbuckle.AspNetCore.Swagger: Esse componente é o middleware e modelo de objeto do Swagger para expor objetos SwaggerDocument como pontos de extremidade JSON.

  • Swashbuckle.AspNetCore.SwaggerGen: Essa biblioteca é um gerador de Swagger que cria objetos SwaggerDocument diretamente de modelos, controladores e rotas. De modo geral, a biblioteca é combinada com o middleware de ponto de extremidade do Swagger para expor o JSON do Swagger automaticamente.

  • Swashbuckle.AspNetCore.SwaggerUI: este pacote é uma versão incorporada da ferramenta Swagger UI. Ele interpreta o JSON do Swagger a fim de criar uma experiência rica e personalizável para descrever a funcionalidade da API Web. Ele inclui os agentes de teste internos para os métodos públicos.

  • CLI do Swashbuckle: Após ter sido instalada, essa ferramenta global do .NET habilita a capacidade de gerar especificações da OpenAPI durante a compilação/publicação. Há um link para baixar a CLI do Swashbuckle no final deste módulo.

Como essas bibliotecas são adicionadas ao seu aplicativo, elas geram e visualizam a documentação da API desde a última versão da sua API. As bibliotecas criam uma documentação dinâmica, sempre em sincronia com o código mais recente.