Documentação de APIs [.Net Core 2.0] com Swagger, ReDoc e Bogus

Documentar é importante, pois além de melhorar a forma que modelamos as nossas APIs para os consumidores, também melhora o que é chamado de Developer Experience, ou seja, a experiência que o desenvolvedor tem ao utilizar as ferramentas, onde o mesmo possa fazer exemplos utilizando a API sem ter que se prender a muitos detalhes e sendo assim conseguir entregar valor mais rápido.

Agora, olha só que legal. Você caro desenvolvedor, com uma simples documentação, tem o poder de mudar a vida de outros desenvolvedores e o ecossistema de desenvolvimento de software. Vamos ver o que a gente precisa para começar!

Criar ou ter uma Web API .Net Core 2.0

Para criar, segue o checklist:

[ ] Instalar o .Net Core 2.0

[ ] Atualizar para a versão 15.3 ou posterior (caso a sua escolha de IDE seja o Visual Studio)

[ ] Criar uma Web API

  • Pela CLI (interface de linha de comando):

Abrir no diretório que deseja criar a API e executar o seguinte comando.

  • Ou pelo Visual Studio:

Instalar os pacotes necessários

Caso tenha realizado os passos anteriores, neste momento você possui uma Web API em .Net Core 2.0. Para facilitar a documentação vamos utilizar alguns pacotes disponíveis, que são:

Swashbuckle.AspNetCore (versão 1.0.0):

Disponibiliza ferramentas do Swagger para documentar APIs ASP.NET Core.

Swashbuckle.AspNetCore.Examples (versão 2.2.2):

Auxilia na geração de exemplos de request e response com dados customizados.

Bogus (versão 18.0.2):

Auxilia na geração de dados falsos, ou seja, quando for testar algum cadastro ou fazer carga de teste para banco de dados, ou apresentar uma interface, não precisa ficar inventando dados, da pra usar alguma ferramenta que torne a apresentação do seu sistema muito mais séria e funcional.

Como podem ver, meus queridos, vai dar samba. Agora, por favor, instale os pacotes.

  • Pela CLI:

1º Opção: Adicionar os pacotes no arquivo .csproj da sua aplicação

Executar o seguinte comando no diretório do arquivo .csproj

2º Opção: Executar o seguinte comando no diretório do arquivo .csproj

  • Ou pelo Visual Studio:

1º Opção: Ferramentas -> Gerenciador de Pacotes do NuGet -> Console do Gerenciador de Pacotes

2º Opção: Ferramentas -> Gerenciador de Pacotes do NuGet -> Gerenciador de Pacotes do NuGet para a Solução ou clicar com o botão direito nas depências e em Gerenciar Pacotes do NuGet.

Selecionar ‘Procurar’, digitar o nome do pacote na caixa de pesquisa, selecionar o pacote e a versão, e clicar em instalar.

Configurar o Swagger

Para uma melhor organização e para não atrapalhar outras configurações que já tenham sido feitas na classe Startup, no caso de um projeto existente, faremos com que a mesma não tenha muitas alterações.

Iremos torná-la uma partial class, adicionar os métodos ConfigureSwaggerService(services) ConfigureSwagger(app, env) e criar outra partial class Startup.Swagger, onde implementaremos os métodos definidos anteriormente.

Agora vamos para o método ConfigureSwagger:

UseStaticFiles — Deve ser utilizado para que o arquivo redoc.min.js fique disponível como um arquivo estático depois de gerado, irei falar um pouco mais sobre ele quando chegarmos na parte da configuração do ReDoc, aguentaí que falta pouco.

UseSwaggerUI — Deve ser utilizado somente em ambiente de desenvolvimento, pois ele expõe a interface interativa do swagger, onde é possível realizar testes de response e request para a aplicação.

UseSwagger — Deve ser utilizado para expor a documentação gerada pelo Swagger como um endpoint json.

Enquanto isso no método ConfigureSwaggerService, podemos incluir no gerador do Swagger:

  • Informações a partir de um arquivo de configuração, como o appsettings.json.

  • Conteúdo do Readme na descrição.

Para isso precisamos adicionar o arquivo README.md no diretório do projeto, configurar propriedade para sempre copiar, caso esta propriedade não seja especificada ao publicar o projeto irá acusar que este arquivo está faltando e não vai dar muito certo.

— Isso pode ser feito direto no .csproj

— Ou pelo Visual Studio

  • Informações do projeto na documentação, como título, versão, descrição, termos de serviço, contato.

  • Informações e método de autenticação utilizado no projeto.

Authentication deve ser substituído pelo método de autenticação, como por exemplo, Bearer.

  • Comentários xml.

Podemos definir os comentários nos métodos:

Ou nos modelos:

Mas para que esses comentários apareçam no xml gerado pelo Swagger, é necessário realizar a seguinte configuração:

— Que pode ser feita diretamente no .csproj

— Ou pelo Visual Studio

Além disso, antes da aplicação ser publicada é necessário realizar o mesmo procedimento feito para o Readme só que para o arquivo .xml gerado, com a opção Copiar se for mais novo, se não em ambiente de desenvolvimento ele vai sempre sobrescrever as suas alterações, ou não vai copiar nada.

  • Descrição de enums como strings e não como seus valores inteiros

 

  • Configuração para definir o que não deve aparecer

Então, se você pensou “Poxa, tem coisa que eu não queria mostrar na documentação, que vida cruel, nada da certo pra mim, o que eu faço da minha vida agora?”, não vou dizer que seus problemas acabaram porque devem existir outros, mas, por hora, isso ta resolvido:

— Esconder controllers:

— Esconder métodos:

No filtro abaixo verificamos se o método possui o atributo HideInDocsAttribute, caso possua nós removemos o caminho dele da lista de caminhos definidos no Swagger.

— Esconder propriedades:

Configurar exemplos com Bogus

Para utilizar exemplos de response e request precisamos habiliar o ExamplesOperationFilter no OperationFilter, como mostrado abaixo:

Adicionar os atributos SwaggerResponse/SwaggerResponseExample para response e SwaggerRequest/SwaggerRequestExample para… suspense… isso, request!

Por enquanto todos os exemplos são gerados em lowerCamelCase, caso o pacote Swashbuckle.AspNetCore.Examples passe a ter suporte para options.SchemaFilter<>() será possível utilizar padrões diferentes como UpperCamelCase/PascalCase, snake_case ou o que a sua imaginação quiser.

Em relação aos modelos, o ideal é criar um para Post, outro para Put e outro para Get, pois se tratando da camada de interface podemos querer níveis de informações diferentes, como:

  • Para buscar:

  • Para criar:

  • Para atualizar:

E cada modelo terá o seu exemplo, sendo que o utilizado para o Get precisará de dois exemplos, um para listas e outro para retornar somente um resultado:

  • Para buscar (um resultado):

  • Para buscar (uma lista):

A gente não é bobo nem nada, logo, aproveitamos o HouseGetExample aqui.

  • Para criar:

  • Para atualizar:

Como podem ver o Bogus entrou no jogo aí e vocês nem sentiram, bem simples de usar, sintaxe fluída e tem uma boa variedade de dados que podem ser gerados em diferentes idiomas, até no nosso querido pt_br.

Contemplar resultado final (Swagger UI):

Execute a aplicação e acesse a url http://localhost:*SuaPorta*/swagger/

Lembra do filtro que nós fizemos? Então, a operação delete não aparece justamente por causa dele.

 Configurar o ReDoc

  • Criar o DocsController.
  • Adicionar o atributo ApiExplorerSettings para não incluir o controller na documentação e o atributo AllowAnonymous para permitir que a Index seja acessada mesmo se houver algum método de autenticação sendo utilizado.

  • Criar a View Index.cshtml

No exemplo da documentação é utilizada a url da última versão, mas nós não vamos fazer isso, porque não queremos possíveis surpresas em produção. Então, vamos definir a Index da forma abaixo:

  • Acessar o diretório wwwroot, criar a pasta scripts e o arquivo redoc.min.js dentro da pasta scripts.
  • Copiar o conteúdo de https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js e colar dentro do arquivo.

Contemplar resultado final (ReDoc):

Execute a aplicação e acesse a url http://localhost:*SuaPorta*/docs/

A operação delete também não aparece aqui, pois o filtro vale para todas as documentações que utilizam o Swagger.

Thaynara Santos

Thaynara Santos

Estudante de Engenharia da Computação no Instituto Infnet e desenvolvedora na MundiPagg. Não tem criatividade para escrever bios, mas compensa tentando fazer códigos de qualidade.
Thaynara Santos

Últimos posts por Thaynara Santos (exibir todos)

Nova API

Para você que já está integrado à nova API, lançamos um novo Dashboard. Para acessá-lo, clique aqui:


NOVO DASHBOARD

API antiga

Caso você continue integrado à nossa API antiga, acesse por aqui o antigo Dashboard:


ANTIGO DASHBOARD
fechar