Once you create API documentation it is important to make it available to the stakeholders. In ideal case, this published documentation would be flexible enough to account for any last-minute changes and also be easy to distribute (in terms of costs as well as time needed to accomplish this). To make this possible we will make use of what was accomplished in my previous post detailing the process of creation of API documentation. Using Swagger UI module in combination with published API documentation in json allows us to create simple HTML documentation that may be used to interact with the APIs as well.
The real key to making your REST API easy to use is good documentation. But even if your documentation is done well, you need to set your company processes right to publish it correctly and on time. Ensuring that stakeholders receive it on time is one thing, but you are also responsible for updates in both the API and documentation. Having this process done automatically provides easy way out of trouble, since your documentation is no longer static deliverable and becomes a living thing. In previous post, I discussed how to integrate Swagger with your Spring application with Jersey. Now it’s time to show you how to create documentation and publish it for others to see.
Nowadays, exposed APIs are finally getting the attention they deserve and companies are starting to recognize their strategic value. However, working with 3rd party APIs can be really tedious work, especially when these APIs are not maintained, ill designed or missing any documentation. That’s why I decided to look around for ways to provide fellow programmers and other team members with proper documentation when it comes to integration. One way to go is to use WADL, which is a standard specifically designed to describe HTTP based web applications (like REST web services). However there are few drawback when using WADL that made me look elsewhere for solutions how to properly document and expose API documentation.
Before we get down to my own additions to existing resources mentioned in my certification guide post I would like to reiterate all resources that I used for my preparation:
- Spring in Action, Third Edition by Craig Walls
- Jeanne’s study notes
- Spring Framework Reference Documentation
When I first heard about this certification I was really excited and wanted to find out what I can about this exam before I start any initiative to pass it. What I found however was the complete lack of resources, guides, information or mock exams of any kind. The only reasonable resource online I was able to find before my exam was a blog post about certification experiences by Jeanne Boyarsky on her well-known blog. However these information are almost 3 years old and few things have changed since then, so please allow me to update you on the current state of the certification process.