Este post foi editado pela última vez por QWERTYU em 12-04-2019 às 14:24
IntroduçãoApós usar asp.net Core para desenvolvimento de APIs, escrever documentação de API deve ser uma tarefa dolorosa para programadores, mas a documentação deve ser escrita, e se não houver requisitos específicos para o formato da documentação, a documentação final depende inteiramente do humor do desenvolvedor. Ou ser mais detalhado, ou mais simples. Então, existe uma maneira rápida e eficiente de construir a documentação da API? A resposta é sim, o Swagger é uma das ferramentas mais populares para gerar documentação de APIs REST!
Por que usar o Swagger como ferramenta de geração de documentação de APIs REST- O Swagger pode gerar um console interativo de APIs que os desenvolvedores podem usar para aprender e experimentar rapidamente APIs.
- O Swagger pode gerar código do SDK cliente para implementações em diversas plataformas.
- Arquivos Swagger podem ser gerados automaticamente a partir de comentários de código em várias plataformas diferentes.
- Swagger tem uma comunidade forte com muitos contribuintes de destaque.
Como usar o Swagger para gerar documentação de API no asp.net núcleo?- Swashbuckle.AspNetCore é um projeto de código aberto que gera documentação Swagger para ASP.NET API Web Core.
- NSwag é outro projeto open-source para integrar Swagger UI ou ReDoc em ASP.NET APIs Web Core. Ele oferece uma forma de gerar código cliente em C# e TypeScript para APIs.
A seguir está um exemplo de Swashbuckle.AspNetCoreQuais são os componentes de um Espadachim?- Swashbuckle.AspNetCore.Swagger: Expõe o objeto SwaggerDocument como um modelo de objeto Swagger e middleware para endpoints JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Um gerador de Swagger que gera objetos SwaggerDocument diretamente a partir de rotas, controladores e modelos. Frequentemente é combinado com middleware de endpoint Swagger para expor automaticamente o JSON Swagger.
- Swashbuckle.AspNetCore.SwaggerUI: Uma versão incorporada da ferramenta Swagger UI. Ele interpreta o Swagger JSON para construir experiências personalizáveis e ricas que descrevem a funcionalidade das APIs Web. Inclui ferramentas de teste integradas para métodos comuns.
Como instalar o Swashbuckle com o vs2017?
A primeira forma: instalar pela janela do Console do Gerenciador de Pacotes
- Vá para Visualizações > Outros Console do Gerenciador de Pacotes do Windows >
- Navegue até o diretório que contém o arquivo TodoApi.csproj
- Por favor, execute o seguinte comando · Install-Package Swashbuckle.AspNetCore
-
Segunda forma: Do diálogo Gerenciar Pacotes NuGet:- Clique com o botão direito no projeto no Explorador de Soluções > Gerencie Pacotes NuGet
- Defina a fonte do pacote para nuget.org
- Digite "Swashbuckle.AspNetCore" na caixa de busca
- Selecione o pacote Swashbuckle.AspNetCore na aba Navegar e clique em Instalar
-
Adicionar e configurar middleware SwaggerIntroduza primeiro o namespace: Adicione o gerador Swagger à coleção de serviços no método Startup.ConfigureServices: emStartup.Configuremétodo, habilitar middleware para servir o documento JSON gerado e a interface Swagger:
Abra o aplicativo e navegue até elehttps://localhost:<port>/swagger/v1/swagger.json。 A documentação resultante que descreve o endpoint é exibida em formato JSON da seguinte forma.
Disponívelhttps://localhost:<port>/confiançaLocalize a interface do Swagger. Navegue pela documentação da API através da interface do Swagger, conforme mostrado abaixo.
Para aplicar a raiz (http://localhost:<port>/) para fornecer a interface Swagger, por favor, coloque oRoutePrefixA propriedade é definida como uma cadeia vazia:
Uso Avançado do Swagger (Personalização e Extensões)Use o Swagger para adicionar informações explicativas à documentação da APIAs seguintes operações de configuração são realizadas no método AddSwaggerGen, que adiciona informações como autor, licença e descrição: As informações da versão de exibição da interface do wagger são mostradas na figura a seguir: Adicionar comentários aos métodos de interfaceVamos clicar primeiro na API, expandir como mostrado na figura abaixo, não pode haver comentários, como adicionar comentários? Adicione comentários no documento com três como mostrado na imagem abaixo, como mostrado abaixo Depois, execute o projeto e volte para o swaggerUI para ver se o comentário aparece Ainda não apareceu, não se preocupe, olhe para baixo! Ativar anotações XMLVocê pode habilitar anotações XML usando os seguintes métodos: - Clique com o botão direito no projeto no Explorador de Soluções e selecione Propriedades
- Veja a caixa de Arquivo de Documento XML na seção Saída da aba Build
-
Ativar anotações XML fornece informações de depuração para tipos e membros comuns não documentados. Se muitas mensagens de aviso aparecerem, por exemplo, a seguinte mensagem indica uma violação do código de aviso 1591:
E se você tiver TOC e quiser cancelar o aviso? Você pode cancelar como mostrado na imagem abaixo
Note o caminho do arquivo de documento xml gerado acima,
Nota: 1. Para sistemas operacionais Linux ou não-Windows, nomes e caminhos de arquivos são sensíveis a maiúsculas minúsculas. Por exemplo, um arquivo "SwaggerDemo.xml" funciona no Windows, mas não no CentOS. 2. Para obter o caminho da aplicação, recomenda-se usar o AppContext.BaseDirectory para obtê-lo Reconstrua e execute o projeto para ver se os comentários aparecem A partir da operação acima, pode-se resumir que a interface do Swagger exibe o <summary> texto interno dos elementos do código de comentário acima como comentários grandes da API! Claro, você também pode adicionar o elemento de observações à documentação de como fazer. Ela pode complementar <summary> as informações especificadas no elemento e fornecer uma interface Swagger mais confiável. <remarks> O conteúdo dos elementos pode conter texto, JSON ou XML. O código é o seguinte: Teste a interface da API usando o SwaggerUIVamos depurar a interface pelo SwaggerUI com um pequeno exemplo
- Clique em uma interface de API que precisa ser testada e depois clique no botão "Testar" à esquerda e à direita de Parâmetros
- Insira um parâmetro na caixa de texto do parâmetro que aparece, como mostrado na imagem a seguir, insira o parâmetro 2
- Clique no botão Executar, e a Resposta formatada mostrada abaixo aparecerá, conforme mostrado na figura abaixo
Bem, é isso para o tutorial de hoje sobre como usar o Swagger para gerar documentação de API em ASP.NET Core WebApi. Espero que seja útil para você aprender a usar o Swagger para gerar documentação de API no ASP.NET Core! resumoEste artigo começa com o ponto crítico de escrever documentação de API manualmente, e depois leva ao Swagger, uma ferramenta que gera automaticamente documentação de API! Depois, por meio de texto e imagens fáceis de entender, vamos demonstrar como usar o SwaggerUI para gerar documentação da API em uma ASP.NET Core WebApi. Por fim, vou apresentar alguns usos avançados do Swagger em ASP.NET Core! Espero que isso ajude você a usar o Swagger no ASP.NET Core!
| 
Publicado em 12/04/2019 14:14:46
|
|
|
|
