REST API documentation with Swagger

Introduction

When you create a REST API for a modern Web application, i.e. by using spring-boot, you need some kind of documentation.

You have do document what a REST endpoint does, which input the endpoints expects, what is validated, and so on, and so on.
Of course your documentation must be updated so it always fits to your delivered application version and the documentation needs to be available to all who want to use your API.

There are many approaches to get that documentation. Some use a Maven plugin to create the documentation during the build of the application. Some put the documentation into a Wiki. Others write Markdown readme files or Microsoft Word documents.

All of those approaches have in common the documentation is located far away from the code and Developers may forget to maintain it and that no documentation follows any standard and may look different.

Swagger for the developer

Fortunately there is Swagger as the reference implementation of the Open API standard which helps the brave developer a lot in archieving a standardized and automatically generated documentation for REST API.

There are many implementations available. As a spring-boot developer I use SpringFox to document my REST APIs. I just need to add some Maven dependencies, add some annotations to my Controllers and Models and as a result I get a nice and standardized API documentation.

If I add the swagger-ui to my project I get a web interface which includes my documentation and as a bonus I can manually try the REST endpoints in that web interface.

As a developer, you normally have the code first approach.

Swagger for the architect

The needs of an software architect is different. When an architect thinks about REST API endpoints no code exist where annotations can be adde.

The software architect needs a tool where he / she can create the complete documentation so a developer is able to do the implementation.

Swagger provides the visual editor tool Swagger Editor to create the API documentation in the Swagger Open API format.

When the documentation is finished server and client stubs for multiple platforms can be generated and re-used by the developers.

As a software architect, you normally have the documentation first approach.

Summary

With Swagger there is no excuse for creating a REST API without any documentation. It does not matter if you have the code first or the documentation first approach. Swagger provides the tools which cover both usecases.

Stop badly documented REST APIs, start using Swagger!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s