Automatic API documentation Swagger and OpenAPI in use
Swagger celebrates its tenth birthday this year and soon finds itself in some new application every day – or even in older ones. What can Swagger do and why is it so popular?
Companies on the topic
Swagger helps implement REST APIs while automating documentation.
(© Sikov – stock.adobe.com)
Swagger is basically three things: A specification, a collection of open source tools, and a commercial offering from Smartbear. It serves the implementation and documentation of REST APIs and consistently pursues the idea that users can try out the functions of the API directly. This makes it easier for Swagger to get started with its own scripting or tool development.
A brief summary: Swagger started in 2011 and was released as an open source project in the same year. The main concerns were an automatic documentation of the API-otherwise a time-consuming, annoying work for the developers – and an interactive user interface. In 2015, Swagger overtook the competition and was renamed the OpenAPI Specification in 2016.
In the course of this, the project was moved to Github, supported by the original developer Smartbear as well as Google, IBM and Microsoft, among others. As so often, the patronage of the founding of the OpenAPI Initiative lay with the Linux Foundation. And so the specifications to run today under OpenAPI, the free Tools are maintained under the name of Swagger in Github and commercial offers of the same Name directly on the Smartbear website Swagger.io.
Perhaps you have never heard or seen anything from Swagger – that’s why we whip up the horse from behind and show a final result first. In the following, the demo project of Smartbear, the so-called Pet Store.
Editor and graphical user interface.
(Picture: Lang / Swagger)
Here we see the Swagger Editor, which you can also use directly online, including the example OpenAPI definition of the Swagger Petstore. In addition, the corresponding graphical user interface Swagger UI can also be found.
How exactly the OpenAPI code is structured can be found in the very good OpenAPI specification on GitHub, but you can already see in the screenshot: The structure is very structured, but much more readable than XML. Swagger UI on the right directly and live the possible API requests-and exactly at the point you can offer (potential) customers and prospects added value very quickly.
Direct API requests via Swagger UI.
(Picture: Lang / Swagger)
This image now shows the API part that allows you to list the pets available in the store by status (“Finds Pets by status”) – on the left as code, on the right as an interactive query. No longer in the picture is the result of the request, i.e. an XML output of the available articles; alternatively, a JSON output could also be created here. Especially the output for Request-URL and curl-command are enormously helpful for Swagger UI of the Petstore – it is exactly these syntax and practice aids that simplify the entry enormously for interested client developers or normal API users.
Swagger Codegen generates code automatically.
(Picture: Lang / Swagger)
You have now seen Swagger Editor and Swagger UI, the third open source tool in the bundle, Swagger Codegen, is still missing-and this is simply hidden in the two menus “Generate Server” and “Generate Client” in the editor.
Using Codegen, server templates can be generated in over 20 languages and client SDKs in over 40 languages. If you try this with the Petstore, you will get packages including installation and configuration instructions, help for Docker, Git repos or, for example, a configuration file to enable autocomplete for the Bash client.
API documentation in ReDoc.
(Picture: Lang / Swagger)
What is still missing is the actual, of course also automatically created documentation – whereby Swagger UI basically already brings a lot of information with it. An example of the Petstore documentation with the redoc markup language can be found at GitHub.
Even in this minimal variant you get a tidy documentation with examples for payloads, HTTP responses, models and also concrete example calls for example servers. But this can be done in more detail.
Real-world example
In the case of the Petstore, one can safely assume that the directive was called “Design first”, but of course Swagger can also be applied to existing code. The procedure is basically pretty straight-forward: annotations are stored in the source code, from which the OpenAPI description is created. For example, you could see it in the monitoring solution Checkmk.
API documentation at Checkmk.
(Picture: Lang / Swagger)
So here again a ReDoc documentation from practice. On the right, in the “Request samples” area, the real magic happens: Here you get very concrete Python and bash scripts for standards such as the library urllib or curl, but also for the promising “API client” httpie, which is more convenient than curl for these purposes and which we also introduce to you explicitly. Of course, you can also store code for C#, PHP or other languages for your projects here.
In addition to ReDoc and the free Smartbear Swagger tools, there are dozens of frameworks, language integration and other open source tools for Swagger/OpenAPI-up to plug-and-play CLIs. A list of open source integrations with Swagger can be found on the project website.
In addition, as mentioned at the beginning, there are the commercial offers of Smartbear, namely SwaggerHub and Swagger Inspector. SwaggerHub delivers the fully hosted version including collaboration tools, extended editor, third-party integrations, automatic mockups and in the enterprise version also API standardization, on-premises installations and the like.
Swagger has become more and more established as a standard in recent years, the importance of APIs has increased exponentially – more and more companies are working according to the motto “Design/API first”, as Zalando, for example, documents in detail. And the httpie slogan “HTTP client for the API era” doesn’t come by chance either. Swagger offers both for the API developer / provider as well as for the API users and third-party developers some interesting features and above all labor savings.
Now what would be an article about development tools without Atlassian-at least a rarity: on Bitbucket you can also find an OpenAPI/Swagger post from Atlassian in the form of a validator as a Java library. So if any API work is pending, OpenAPI would certainly be worth a Jira ticket.
(ID:47375265)
