3 Swagger tools to help you document your API

Why do we use Swagger at Dharma?

At Dharma, we value having proper documentation. Now documenting your API endpoint might not be the first thing you think of regarding internal documents, but these documents are very valuable for everyone that works on the project. A frontend developer might use the documentation to make a seamless connection between their client and your API.

New backend developers can use the documentation to better understand the codebase and run some tests locally. At some point an external entity might want to make use of your API. Sometimes even the customers are interested in understanding their product a bit better. Of course there are loads of ways to document your APIs, but Swagger offers good looking, interactive and easily testable documentation.

What is Swagger?

Swagger is a set of open source tools that can be used to design and (automatically) document your APIs. There are currently 3 open source tools available: Swagger UI, Swagger Editor and Swagger Codegen. In this blog we will explain how these tools work, and how you can use them to design and/or document your APIs.

Swagger UI

Swagger UI is an open source tool that will visualise all the endpoints in your API. When searching for Swagger, this is likely the first tool you came across. Aside from it looking great, it also has an interactive part since you can actually call an endpoint via Swagger UI itself. It even works with authorised endpoints by providing an api key or by providing credentials for an OAuth2 implementation. Swagger provides a great demo on this.

The user interface get’s generated by providing either a YAML or JSON file that are based on the OpenAPI Specification. Creating this file manually can be a lot of work, this is where the Swagger Editor comes in handy. Swagger automation is also something that can be done, some languages have packages that will automatically create this file based on the code in your project, this way the documentation will always be up to date without needing to do anything for it, which is great!

Swagger Editor

When you are manually creating the YAML or JSON file required for Swagger UI, you should use the Swagger Editor. This open source editor will show you your file on the left and the generated UI on the right. Any update to the file will be shown live in the user interface. It will even show some errors, for example a DELETE operation should not have a request body. The Swagger Editor will also give you the option to, based on your file, generate a server or a client which can be done with Swagger Codegen.

Swagger Codegen

Swagger Codegen is an open source tool that can generate pieces of code for your server or client. It can generate code for servers in over 20 different languages and 40 different languages for clients. These pieces of code can be used to simulate server responses from API calls or create Software Development Kits to help you integrate your API into your system.

An example of Swagger at Dharma

At Dharma, we have multiple projects which have their APIs documented by Swagger. One notable example is a big Java project we have which consists of multiple applications. The project uses Spring as a framework, and springdoc-openapi as a package to automatically generate our Swagger documentation.

Since the project is properly set up, we only had to require the package and add some settings in our properties file. At that point, Swagger UI was available and the package even provides a separate endpoint that just returns the JSON output Swagger would normally use. Since this output follows the OpenAPI / Swagger Specification which is broadly used it can be used to for example import into Postman or Insomnia to automatically add all the endpoints to your client.

Conclusion

Swagger has some very useful tools to play around with regarding your existing or future API. You can choose to design your API from the ground up, or just use other tools to document the current endpoints for all the interested parties. With its friendly user interface, interactiveness and easily testable documentation it is a great choice for your existing or future APIs.