Swagger - documentação inteligente para sua API da web RESTful - Revisão do desenvolvedor de back-end júnior para iniciantes

Prefácio

A equipe na qual dei meus primeiros passos no campo da escrita de código industrial estava desenvolvendo uma API conveniente para a funcionalidade de um produto de software em C # (por conveniência, vamos chamá-la, digamos, da letra E), que existe há muitos anos e se estabeleceu no mercado de um lado muito positivo . E aqui, ao que parece, o jovem Padawan ainda não deve ter perguntas, mas imagine que mais cedo, provavelmente, você escreveu suas próprias APIs da web, mas é improvável para um público amplo, o que significa que você viveu com o princípio "eu mesmo o criei - Estou usando ”e, se alguém estivesse interessado na funcionalidade da sua API, você provavelmente teria lançado a ele um arquivo PDF com instruções detalhadas (pelo menos eu teria feito exatamente isso). “Onde posso ver a API funcional” - perguntei ao líder da equipe, esperando obter um link para um documento de texto. "Dê uma olhada no Swagger", ele respondeu.

Espere, como é que o produto está funcionando com sucesso há muito tempo e a API que você está gravando apenas agora?

É isso mesmo, até recentemente, E não tinha uma API pública conveniente como tal. De fato, todo o trabalho foi feito através da interface da Web e o back-end consistia em muitos microsserviços internos, com os quais era impossível integrar de fora sem uma compreensão clara da lógica de negócios interna, sem mencionar o fato de que eles próprios consistiam em uma grande proporção de legado. Era necessário prestar atenção aos clientes que desejam interagir diretamente diretamente com o servidor, o que significa fornecer a eles uma API bonita e conveniente. O que é necessário para isso? Tudo o que foi escrito um pouco antes é pegar e estabelecer trabalho com todos os microsserviços internos, além de fornecer documentação conveniente e bonita, tornando-a bonita, compreensível e, o mais importante, com sucesso comercial.

Bem, então o que é Swagger e qual é a sua utilidade para o mundo?

Em essência, o Swagger é uma estrutura para a especificação da API RESTful. Seu charme reside no fato de possibilitar não apenas a visualização interativa da especificação, mas também o envio de solicitações - a chamada interface do usuário do Swagger, é a seguinte:



Como podemos ver - uma descrição completa dos métodos, incluindo modelos, códigos de resposta, parâmetros de consulta - em geral, claramente.

E como isso funciona?

Ótimo guia para implementar o Swagger no ASP.NET Core
do zero está aqui neste artigo.

A ideia é configurar a exibição usando anotações especiais para métodos de API, aqui está um exemplo:

Swagger codegen

Se você realmente deseja, pode gerar diretamente um cliente ou servidor de acordo com a especificação da API Swagger, para isso é necessário um gerador de código Swagger-Codegen. A descrição da documentação, eu acho, não precisa ser explicada:

Este é o projeto Swagger Codegen, que permite a geração de bibliotecas de clientes API (geração SDK), stubs de servidores e documentação automaticamente, com base em uma especificação OpenAPI. Atualmente, os seguintes idiomas / estruturas são suportados:

• Clientes da API: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 ou posterior), C ++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Biblioteca cliente da API do Google para Java, com segurança), Kotlin, Lua, Node.js (ES5, ES6, AngularJS com anotações do Google Closure Compiler) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x), Texto datilografado (Angular1.x, Angular2.x, Buscar, jQuery, Nó)
• Stubs de servidor: Ada, C # (ASP.NET Core, NancyFx), C ++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (servidor de ferrugem), Scala (Finch, Lagom, Scalatra)
• Geradores de documentação da API: HTML, Confluence Wiki
• Arquivos de configuração: Apache2
• Outros: jmeter

Outras informações, em particular as instruções de uso, são apresentadas aqui:
Informação geral

E aqui: Detalhes

Conclusão

Esta foi uma breve visão geral para desenvolvedores de API iniciantes, cujo objetivo era fornecer uma imagem geral do que é o Swagger, por que ele é necessário e quais são as principais vantagens do meu ponto de vista pessoal.