I use clojure for creating REST API. How to generate REST documentation automatically?

Question

I'm writing clojure rest service (with ring, compojure and liberator) and would like to automatically generate API documentation for all my REST API. It's very tedious to generate it manually. Is there any way to use annotations or something like this? It will be cool if I can do it with lein gen-rest-docs.

Answer 1

Give ring-swagger a try. It has a compojure, fnhouse and Pedestal options

Answer 2

The "Uniform Interfaces" property of the REST architecture style does not encourage documentation for individual endpoints. In REST you rely on self descriptive messages and hyperlinks to drive the application.

While I can see that you need to document your API, I recommend to focus on documenting how the media types are applied to your domain and general assumptions in the implementation. This typically covers authorization, SLAs. If you make proper use of media types and hyperlinks, then the individual resources do not need much documentation anymore.

If that's no option for you then be aware the you have an RPC architecture. In this case ring-swagger and similar solutions can help.