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

Foreword

The team, in which I took my first steps in the field of writing industrial code, was developing a convenient API to 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 they 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 to see api functionality,” I asked the team leader, expecting to receive a link to a text document. “Look at Swagger,” he replied.

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

That's right, as such, a convenient public API from 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 set up work with all internal microservices, 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 like:

')





As we can see, a complete description of the methods, including models, response codes, query parameters, is in general, visual.

And how does it work?

A great guide for implementing 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. Description from the documentation, I think, is not required to explain:

This is the Swagger Code project, the client 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

This 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.