In the last post, I noted that I have been documenting REST APIs for the last couple of years. The documentation is manual (not automated to generate documentation out of code comments). We have a template to follow for documenting the basic components, such as headers, methods, request and response classes, and parameters and messages. We are looking into various tools to streamline the process, including Swagger (http://swagger.io).
Stephen Judd of OpenCredo gave Swagger a positive rating in his article Documenting REST APIs – a tooling review (July 28, 2015). Judd describes the tool, and his experience using it with the Java library Springfox. He provides an example Books API to illustrate the outcome. This screenshot from Judd’s article shows the GET method tab expanded, with documentation for the response class.
The resulting documentation is attractive and straightforward. The Swagger tool includes an Editor for designing the API specification, and a Web UI that converts the specification into API documentation in web page format. A tool like Swagger would definitely improve the documentation process.