How to create RESTful service documentation

Recently I got hit by a issue of documenting the REST services that I was developing using Apache CXF. Intent was to create a document or a wiki that the third-party which was supposed to use these services could use it.

First thing I did was generated JavaDocs for the services, DTO’s and Interfaces and handed that over to the concerned team. But that was not enough and I was not happy, so did some research to find out how to create a interactive REST Web Service documentation.

As I explored, I found out that there are multiple ways we can do this. But there is NO STANDARD as to how this should be done and the reasons for it are explained beautifully in this SO answer.

But I was curious to do this and evaluated some of the frameworks available:

  1. Swagger UI: (I finally used this!) Beautiful documentation generated, with a interactive interface where people can try out the services on your hosted system. I was impressed.
  2. Enunciate: Generated static HTML based documentation for your services with input/output params as model’s. Works on JavaDocs.

Against all odds now I have swagger-ui integrated into my project and has created a separate blog on how-to-do-this if you are using the same tech-stack as I was using.