Contract Driven REST API Design10 Apr 2015
Apidoc.js is a great inline documentation tool for RESTful web APIs.
It goes really well with Spring REST applications, you just define your API documentation as inline comments in your classes and execute the apidoc command to parse the source files and generate a static HTML documentation out of them.
With this lightweight technology it is easy to follow a contract driven REST API design that I found really
useful in my past project.
The process we followed was to design the API for the resource, document the API using the Apidoc annotations and generate a HTML documentation out of it.
The generated documentation was then published to a server and before starting the implementation we reviewed it together with fellow team members and other possible customers of the future API.
The implementation could only begin when the API was reviewed, adjusted and accepted.
To install Apidoc you need npm package manager to be installed first.
Assume you are using mac with brew it goes as easy as:
After the successful installation the npm command should work in the terminal giving you the “usage…” page.
Npm installation guide can be found here: node & npm
Apidoc needs to be configured by creating an apidoc.json file in your project root directory.
To generate the documentation you need to configure maven to execute the apidoc command. The minimum configuration for apidoc command execution requires configuring the input and output folders.
You also need maven reports plugin to generate reports as part of the site phase.
At this point the mvn clean site should trigger Apidoc execution, however it will not generate output by default without having Apidoc documentation embedded in your code.
Document API with Apidoc
You can now start documenting your api with using the available params.
See a complete class configuration working in the book-inventory-boot project: BookResource.java.
The Generated Documentation
The generated configuration will be in the target/apidoc directory as configured in the pom.xml. It looks like this:
See the full documentation: Book Inventory API
Documentation is one of the key factor of determining how usable your API will be.
Without it even the best designed API will cause headache to the users need to rely on it.
Furthermore generating the documentation before implementation, agree in the contract upfront, minimises the changes you need to make in your code.
See the complete example in book-inventory-boot repository.