GitHub PullRequestReviewCommentEvent at 2014-02-12 14:07:15
Repository: ninja-squad.github.com
Actor: cexbrayat
Payload: {"comment":{"url":"https://api.github.com/repos/Ninja-Squad/ninja-squad.github.com/pulls/comments/9668034","id":9668034,"diff_hunk":"@@ -0,0 +1,127 @@\n+---\n+layout: post\n+title: Generate your REST API documentation with Asciidoctor and Gradle\n+author: jbnizet\n+tags: [asciidoctor, gradle, doc, rest]\n+---\n+\n+Generating documentation for a Java API is quite easy. Javadoc is a great and easy to use tool, integrated in every Java build tool,\n+and produces a result that every Java developer is (or should be) comfortable with.\n+\n+Generating documentation for a REST API is not as easy. You can implement a RESTful backend in any language you can imagine. Once you have chosen one\n+(Java, in our case), the way you define it and implement it depends on the frameworks you choose: JAX-RS, Spring MVC, etc. Even assuming you have a tool \n+understanding your framework, it also has to understand how your JSON serializer (Jackson, in this case) is configured and works. And if \n+you use annotations to define your validation constraints, it also has to understand them. All in all, automating the documentation generation\n+of a REST API is much harder than doing it for a Java API.\n+\n+We did some experiments with [Swagger](http://swagger.wordnik.com/), but were not really satisfied with the result. Its \n+[Spring MVC integration](https://github.com/martypitt/swagger-springmvc) doesn't handle all the signatures of the Spring MVC\n+controller methods, the generated validation constraints are incorrect, and the end result is a bit rough. There's a good reason why\n+popular REST API documentations like the Twitter API are not automatically generated, but carefully hand-crafted, so we finally decided to go this way, \n+and this post describes how we did it.\n+\n+## Asciidoc\n+\n+First af all, we wanted to be free to organize the documentation as we wanted, to provide introductory paragraphs about the general\n+conventions, etc. Being able to generate it in various formats (HTML, PDF, etc.) is also something we found useful. And an automatically generated\n+table of contents is great as well. So we decided\n+to go with [Asciidoc](http://www.methods.co.nz/asciidoc/) and, more specifically, Asciidoctor. A typical service documentation \n+looks like this in our Asciidoc document:\n+\n+    == Messages\n+\n+    Messages can be read, created, updated and deleted by a user having the \n+    ROOT role. A corpus ID is used to identify the cluster, database and \n+    collection to use. Only collections that are not used in any campaign \n+    can be modified.\n+\n+    === Read\n+\n+    [cols=\"h,5a\"]\n+    |===\n+    | URL\n+    | /api/admin/corpora/[corpusId]/messages/[messageId]\n+\n+    | Method\n+    | GET\n+\n+    | Response Body\n+    | include::{snippetDir}/message.json.adoc[]\n+    |===\n+\n+You can add any information you like, in any format you like, in the documentation. This is a real advantage that allows making your documentation","path":"_posts/2014-02-25-rest-api-doc-with-asciidoctor-and-gradle.md","position":52,"original_position":52,"commit_id":"aea09df66f9c98aa0d7500880fb8c3dd064aa197","original_commit_id":"aea09df66f9c98aa0d7500880fb8c3dd064aa197","user":{"login":"cexbrayat","id":411874,"avatar_url":"https://gravatar.com/avatar/0f0edb7904c4eea5f1b60fba0bf88537?d=https%3A%2F%2Fidenticons.github.com%2F3fbe6e0a4594b89df5928d444c01bb14.png&r=x","gravatar_id":"0f0edb7904c4eea5f1b60fba0bf88537","url":"https://api.github.com/users/cexbrayat","html_url":"https://github.com/cexbrayat","followers_url":"https://api.github.com/users/cexbrayat/followers","following_url":"https://api.github.com/users/cexbrayat/following{/other_user}","gists_url":"https://api.github.com/users/cexbrayat/gists{/gist_id}","starred_url":"https://api.github.com/users/cexbrayat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cexbrayat/subscriptions","organizations_url":"https://api.github.com/users/cexbrayat/orgs","repos_url":"https://api.github.com/users/cexbrayat/repos","events_url":"https://api.github.com/users/cexbrayat/events{/privacy}","received_events_url":"https://api.github.com/users/cexbrayat/received_events","type":"User","site_admin":false},"body":"Not sure about *allows making*... maybe *allows to make*?","created_at":"2014-02-12T14:07:15Z","updated_at":"2014-02-12T14:07:15Z","html_url":"https://github.com/Ninja-Squad/ninja-squad.github.com/pull/77#discussion_r9668034","pull_request_url":"https://api.github.com/repos/Ninja-Squad/ninja-squad.github.com/pulls/77","_links":{"self":{"href":"https://api.github.com/repos/Ninja-Squad/ninja-squad.github.com/pulls/comments/9668034"},"html":{"href":"https://github.com/Ninja-Squad/ninja-squad.github.com/pull/77#discussion_r9668034"},"pull_request":{"href":"https://api.github.com/repos/Ninja-Squad/ninja-squad.github.com/pulls/77"}}}}