I tackled details of integration, documentation creation as well as exposition of documentation using Swagger and its module Swagger UI. One of obvious shortcomings that might be serious concern for people managing their API documentation is fine-grained control over what is published and what stays hidden. There are several reasons to decide to hide something from users. First might be the lack of relevance of introspected information that just don’t belong to the documentation. Other big issue might be security concerns as well as the design of API documentation itself.

Continue reading “Spring Rest API with Swagger – Fine-tuning exposed documentation” →

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.

Continue reading “Spring Rest API with Swagger – Exposing documentation” →

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.

Continue reading “Spring Rest API with Swagger – Creating documentation” →