Swagger: documentación inteligente para su API web RESTful: revisión del desarrollador back-end junior para novatos

Prólogo

El equipo en el que di mis primeros pasos en el campo de la escritura de código industrial estaba desarrollando una API conveniente para la funcionalidad de un producto de software en C # (por conveniencia, digamos, la letra E), que ha existido durante muchos años y se ha establecido en el mercado con un lado muy positivo. . Y aquí, al parecer, el joven Padawan aún no debería tener ninguna pregunta, pero imagina que antes, muy probablemente, por supuesto, escribiste tus propias API web, pero es poco probable para una audiencia amplia, lo que significa que viviste según el principio "Yo mismo lo creé, Lo estoy usando ", y si alguien estuviera interesado en la funcionalidad de su API, entonces probablemente le habría arrojado un archivo pdf con instrucciones detalladas (al menos lo habría hecho). "¿Dónde puedo ver la API funcional?", Le pregunté al líder del equipo, esperando obtener un enlace a un documento de texto. "Echa un vistazo a Swagger", respondió.

Espera, ¿cómo es que el producto ha estado funcionando con éxito durante mucho tiempo y la API que le estás escribiendo solo ahora?

Así es, hasta hace poco, E no tenía una API pública conveniente como tal. De hecho, todo el trabajo se realizó a través de la interfaz web, y el back-end consistió en muchos microservicios internos, con los cuales era imposible integrarse desde el exterior sin una comprensión clara de la lógica comercial interna, sin mencionar el hecho de que ellos mismos consistían en una gran proporción del legado. Era necesario prestar atención a los clientes que querían interactuar directamente directamente con el servidor, lo que significa proporcionarles una API hermosa y conveniente. ¿Qué se requiere para esto? Todo lo que se escribió un poco antes es tomar y establecer el trabajo con todos los microservicios internos, así como proporcionar documentación conveniente y hermosa, haciéndola hermosa, comprensible y, lo más importante, comercialmente exitosa.

Bueno, entonces, ¿qué es Swagger y cuál es su utilidad para el mundo?

En esencia, Swagger es un marco para la especificación RESTful API. Su encanto radica en el hecho de que hace posible no solo ver interactivamente la especificación, sino también enviar solicitudes, la llamada interfaz de usuario Swagger, así es como se ve:



Como podemos ver, una descripción completa de los métodos, incluidos modelos, códigos de respuesta, parámetros de consulta, en general, claramente.

Y como funciona

Gran guía para implementar Swagger en ASP.NET Core
desde cero está aquí en este artículo.

La idea es configurar la pantalla usando anotaciones especiales para los métodos API, aquí hay un ejemplo:

Codegen Swagger

Si realmente lo desea, puede generar directamente un cliente o servidor de acuerdo con la especificación API Swagger, para esto necesita un generador de código Swagger-Codegen. La descripción de la documentación, creo, no necesita ser explicada:

Este es el proyecto Swagger Codegen, que permite la generación de bibliotecas de cliente API (generación de SDK), stubs de servidor y documentación automáticamente con una especificación OpenAPI. Actualmente, se admiten los siguientes lenguajes / marcos:

• Clientes API: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 o 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, Google API Client Library para Java, Descanso seguro), Kotlin, Lua, Node.js (ES5, ES6, AngularJS con anotaciones del compilador de cierre de Google) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (óxido, servidor de óxido), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x), mecanografiado (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Trozos 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 óxido), Scala (Finch, Lagom, Scalatra)
• Generadores de documentación API: HTML, Confluence Wiki
• Archivos de configuración: Apache2
• Otros: jmeter

Aquí se presenta otra información, en particular las instrucciones de uso:
Información general

Y aquí: detalles

Conclusión

Esta fue una breve descripción visual para desarrolladores principiantes de API, cuyo objetivo era proporcionar una descripción general de qué es Swagger, por qué es necesario y qué ofrece las principales ventajas desde mi punto de vista personal.