Swagger - Documentation intelligente de votre API Web RESTful - Revue de développeur back-end junior pour les débutants

Préface

L'équipe dans laquelle j'ai fait mes premiers pas dans le domaine de l'écriture de code industriel développait une API pratique pour la fonctionnalité d'un produit logiciel en C # (pour plus de commodité, appelons-la, disons la lettre E), qui existe depuis de nombreuses années et s'est imposée sur le marché de manière très positive. . Et ici, il semble que le jeune Padawan ne devrait pas encore avoir de questions, mais imaginez que plus tôt, bien sûr, vous avez écrit vos propres API Web, mais c'est peu probable pour un large public, ce qui signifie que vous avez vécu selon le principe «Je l'ai créé moi-même - Je l'utilise ", et si quelqu'un était intéressé par la fonctionnalité de votre API, vous lui auriez probablement jeté un fichier pdf avec des instructions détaillées (au moins je l'aurais fait juste). «Où puis-je voir l'api fonctionnelle» - ai-je demandé au chef d'équipe, en espérant obtenir un lien vers un document texte. "Jetez un œil à Swagger", répondit-il.

Attendez, comment se fait-il que le produit fonctionne correctement depuis longtemps, et l'API que vous y écrivez seulement maintenant?

C'est vrai, jusqu'à récemment, E n'avait pas d'API publique pratique en tant que telle. En fait, tout le travail a été effectué via l'interface Web, et le back-end était composé de nombreux microservices internes avec lesquels il était impossible de s'intégrer de l'extérieur sans une compréhension claire de la logique métier interne, sans parler du fait qu'ils constituaient eux-mêmes une grande partie de l'héritage. Il était nécessaire de faire attention aux clients qui souhaitent interagir directement directement avec le serveur, ce qui signifie leur fournir une API belle et pratique. Que faut-il pour cela? Tout ce qui a été écrit un peu plus tôt est de prendre et d'établir nous-mêmes le travail avec tous les microservices internes, ainsi que de fournir une documentation pratique et belle, ce qui la rend belle, compréhensible et, surtout, réussie commercialement.

Eh bien, qu'est-ce que Swagger et quelle est son utilité pour le monde?

En substance, Swagger est un cadre pour la spécification de l'API RESTful. Son charme réside dans le fait qu'il permet non seulement de visualiser la spécification de manière interactive, mais également d'envoyer des requêtes - la soi-disant Swagger UI, voici à quoi cela ressemble:



Comme nous pouvons le voir - une description complète des méthodes, y compris les modèles, les codes de réponse, les paramètres de requête - en général, clairement.

Et comment ça marche?

Grand guide pour implémenter Swagger dans ASP.NET Core
à partir de zéro est ici dans cet article.

L'idée est de configurer l'affichage à l'aide d'annotations spéciales pour les méthodes API, voici un exemple:

Swagger codegen

Si vous le souhaitez vraiment, vous pouvez générer directement un client ou un serveur conformément à la spécification de l'API Swagger, pour cela, vous avez besoin d'un générateur de code Swagger-Codegen. La description de la documentation, je pense, n'a pas besoin d'être expliquée:

Il s'agit du projet Swagger Codegen, qui permet de générer des bibliothèques clientes API (génération SDK), des stubs de serveur et de la documentation automatiquement avec une spécification OpenAPI. Actuellement, les langages / frameworks suivants sont pris en charge:

• Clients API: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 ou version ultérieure), 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 for Java, Rest-Guaranteed), Kotlin, Lua, Node.js (ES5, ES6, AngularJS avec annotations du compilateur de fermeture Google) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rouille, rouille-serveur), Scala (akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Stubs de serveur: 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 (rust-server), Scala (Finch, Lagom, Scalatra)
• Générateurs de documentation API: HTML, Confluence Wiki
• Fichiers de configuration: Apache2
• Autres: jmeter

D'autres informations, en particulier les instructions d'utilisation, sont présentées ici:
Informations générales

Et ici: Détails

Conclusion

C'était un bref aperçu visuel pour les développeurs débutants d'API, dont le but était de fournir une image générale de ce qu'est Swagger, pourquoi il est nécessaire et ce qu'il donne les principaux avantages de mon point de vue personnel.