Swagger - smart documentation for your RESTful web API - Junior back-end developer review for beginners

Foreword

The team, in which I took my first steps in the field of writing industrial code, was engaged in developing a convenient API for the functionality of a software product in C # (for convenience, let's call it, say, the letter E), which has existed for many years and has proven itself in the market from a very positive side . And here it seems that the young Padawan should not have any questions yet, however, let us imagine that you previously, most likely, of course, wrote your own web-API, but it is unlikely for a wide audience, which means you lived according to the principle “He created I use it ”, and if suddenly someone would be interested in the functionality of your API, then you probably would have thrown him a pdf-file with detailed instructions (at least I would have done just that). “Where can I see the functionality of api?” I asked the team leader expecting to receive a link to a text document.

Wait, how is it that the product has been successfully operating for a long time, and you write API to it just now?

That's right, as such, a convenient public API for E until recently did not exist. In fact, all the work took place through a web interface, and the back-end consisted of many internal microservices with which it was impossible to integrate from the outside without a clear understanding of internal business logic, let alone that they themselves consisted of a large proportion of Legacy. It was necessary to pay attention to customers who want to directly interact with the server, and therefore provide them with a beautiful and convenient API. What is required for this? All that was written a little earlier was to take and organize work with all internal microservices ourselves, as well as provide convenient and beautiful documentation, making it beautiful, understandable, and most importantly - commercially successful.

Well, so what is Swagger and what is its utility to the world?

In essence, Swagger is a framework for the RESTful API specification. Its charm lies in the fact that it provides an opportunity not only to view the specification online, but also to send requests - the so-called Swagger UI, this is how it looks:



As we can see, a complete description of the methods, including models, response codes, request parameters - in general visually.

And how does it work?

An excellent guide to introducing Swagger in ASP.NET Core
from scratch is here in this article.

The idea is to configure the display using special annotations for API methods, here is an example:

Swagger codegen

If you really want to, you can directly generate a client or server according to the Swagger API specification, for this you need a Swagger-Codegen code generator. I don’t need to explain the description from the documentation:

This is the Swagger Code project, which stubs and documentation automatically given an OpenAPI Spec. Currently, the following languages ​​/ frameworks are supported:

• API clients: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 or later), 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-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) 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), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Server stubs: 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)
• API documentation generators: HTML, Confluence Wiki
• Configuration files: Apache2
• Others: JMeter

Other information, in particular the instructions for use, is presented here:
General Information

And here: Detailed information

Conclusion

It was a brief visual overview for novice API developers, the purpose of which was to provide a general picture of what Swagger is, why it is needed and what it provides with the main advantages from my personal point of view.