API Documentation using Swagger, Swagger2Markup and AsciiDoc
“Application Programming Interfaces (APIs) can only be as good as their documentation”
API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments and even more.
APIs are intended to be consumed. If you have a great project but you do not provide elaborate API documentation on how to use it, then it loses it’s ease of use. Therefore, it’s pivotal to ensure that users can quickly get started in implementing them without many hurdles. Furthermore, well-explained documentation saves support time and costs.
This article explains the steps to setup a swagger UI for your spring project and also to automate the generation of static API documentation in the form of a PDF/HTML file from the swagger UI.
Setup Swagger UI to your REST API
To start with the API documentation, first is to set up swagger for your REST API. An example of it can be found at the following repository.
Add the following dependencies to the build.gradle file in your project.
compile group: ‘io.springfox’, name: ‘springfox-swagger2’, version: ‘2.7.0’
compile group: ‘io.springfox’, name: ‘springfox-swagger-ui’, version: ‘2.7.0’
The configuration of Swagger centers around the Docket bean.
After defining the Docket bean, its select() method returns an instance of ApiSelectorBuilder, which provides a way to control the endpoints exposed by Swagger.
We can configure predicates for selecting RequestHandlers with the help of RequestHandlerSelectors and PathSelectors. Using any() for both will make documentation for our entire API available through Swagger.
To Generate swagger UI document for your REST API you would need to use Swagger annotations to describe the APIs written . An sample is provided in the Repository for GET/POST/PUT/DELETE APIs.
Generate PDF/HTML file from swagger using a gradle task
Sometimes relying exclusively on the generation of the documentation with swagger-UI may not be sufficient. There might be some aspects(like common use cases and workflows) that need to be described manually and also a requirement to store/provide the API documentation for offline use.
In such cases writing the API documentation manually is a painful task. The primary objective here is to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation produced by Swagger. The result is intended to be an up-to-date, easy-to-read, on- and offline user guide.
The approach described here makes use of the following two plugins in addition to the swagger UI.
- Swagger2Markup: Swagger2Markup converts a Swagger JSON or YAML specification into asciidoc , which can be combined with hand-written Markup documentation. The Swagger source file can be located locally or remotely via HTTP. Internally Swagger2Markup uses the official swagger-parser and markup-document-builder.
- Asciidoc: AsciiDoc is a text document format for writing documentation, articles, books, ebooks, slideshows, web pages and blogs. AsciiDoc files can be converted to HTML, PDF and EPUB. AsciiDoc is best suited for describing public APIs
I have used this approach in an sample project on GitHub.(Link to Repo)
Let us take a look at the main implementation details of it.
The two tasks convertSwagger2markup and asciidoctor added to the build.gradle file of the project are responsible for generation of API documentation file.
- The convertSwagger2markup task depends on the test present in the repository. The test createSpringfoxSwaggerJson() generates a swagger.json file that contains the latest JSON response from swagger and this file is then used by swagger2markup to convert it to .adoc files.
- The asciidoctor task depends on the convertSwagger2markup task. It converts the generated .adoc files into html/PDF files.
The asciidoctor task uses the index.adoc file located at src/docs/asciidoc to get the location of the files to be used for generating PDF/HTML files.
Currently it includes the path of .adoc files generated by the swagger2Markup task and some additional files that are created manually.
The additional files mentioned in the document can contain any handwritten additional documentation that is not generated by swagger and is required to be added to the PDF. It combines it with the swagger generated documentation to generate a single document.
You can also include any other additional files required in this index.adoc file.
To generate a document simply run the following command from the project directory.
gradlew clean asciidoctor
IT will generate a PDF and html document at the path given below.
build/asciidoc/pdf or build/asciidoc/html5
Here is a snapshot of the sample documents generated by the plugin.
Conclusion
API documentation is important for creating good developer experience. The process explained above helps to generate API documentation for offline use that is up-to-date and can also blend swagger generated and manually written documentation at the same time and merge it into one document.
Yes, it does require additional effort on the part of the developer to use swagger annotations for API and setup this tool chain but it also justifies the benefits provided by it.
References
- https://blog.api.rakuten.net/best-practices-for-writing-api-documentation/
- https://github.com/Swagger2Markup/swagger2markup
3. https://phauer.com/2017/rest-api-documentation-swagger-asciidoc/
