2

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.

Curiosity
  • 651
  • 1
  • 5
  • 12

2 Answers2

5

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.

ordnungswidrig
  • 3,140
  • 1
  • 18
  • 29
  • I see. If I would like to document server responses (json) I should use swagger, don't I? I have a special wiki page for front-end developers with examples of all unobvious responses. The main problem is necessity to support both codebase and the wiki page. – Curiosity Jan 21 '15 at 18:59
2

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

DanLebrero
  • 8,545
  • 1
  • 29
  • 30
  • Could you elaborate on using this to generate documentation? – Nathan Davis Jan 20 '15 at 04:51
  • 1
    Depending on which lib you are using, you will find an example on their project page. For example, for compojure see https://github.com/metosin/compojure-api. Links to each lib are in the ring-swagger page – DanLebrero Jan 20 '15 at 11:06