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!
Flexguse's Blog 