Rails API Doc Generator ======================= RESTTful API documentation generator for Rails. It supports Rails 2.1 and greater. It generates a set of HTML views in the public directory. Parses the desired controllers and generates appropriate views. Currently does not read routes.rb and requires manual entry of routes Installation ============ `gem install rapi_doc` Usage ===== Run `rake rapi_doc:setup` to generate default Haml template files along with default styles. These files are in `/config/rapi_doc` folder. Then invoke the generation by calling: `rake rapi_doc:generate` It will analyze the `routes.rb` files and find the controller files in app/controllers directory that may have the annotation. Only controllers actions with annotation will be parsed and generated the HTML output using the template files and styles in the `config/rapi_doc` folder. The final result is placed in `public/apidoc/`. `rake rapi_doc:generate confirmation=true` This rake task is the same as `rake rapi_doc:generate` but it will acquire your confirmation to generate API doc for each controller. `rake rapi_doc:clean` This rake task will remove the documentation thus generated. `rake rapi_doc:distclean` This rake task will remove the documentation and also the Haml template files and styles created by the `rake rapi_doc:setup` Markup Reference ================ Controller methods and controllers themselves are documented by annotating them with "method markers" and "resource markers" enclosed in "apidoc" comments, similar to that in RDoc. # =begin apidoc ... method markers # =end A] Method markers ----------------- Method markers are specified like this: # <:: All method markers are optional. # method: HTTP request type such as GET or POST # access: access restrictions such as FREE, RESTRICTED for paid subscribers, etc # return: list of return data-formats like [JSON|XML] and what the return data means # param: name and type of the parameter expected # output: output format like JSON, XML. It is recommended that it should include an example of such data. # Each output marker must end with ::output-end:: on a separate line. # request: a request generating code example # response: a response processing code example You can define your own custom method markers as well. They will be available as the instance variables against which the _resource_method.html.erb template will be evaluated. Any other information that needs to be shown in the view can be specified in the apidoc comments as well. It will be shown under the "Description" section for the method in the view. B] Resource markers ------------------- A resource, which is normally a controller object, can also be annotated with apidoc comments. Method markers are specified the same way as the method markers: # <:: # # xml: xml representation of the resource # json: json representation Just like in method marker, any other information that needs to be shown in the view can be specified in the apidoc comments as well. It will be shown under the "Description" section for the method in the view. C] Documentation Example --------------------- # =begin apidoc # url:: /books # method:: GET # access:: FREE # return:: [JSON|XML] - list of book objects # param:: page:int - the page, default is 1 # param:: per_page:int - max items per page, default is 10 # # output:: json # [ # { "created_at":"2011-12-05T09:46:11Z", # "description":"As with the last several books in the series, V Is for Vengeance was a long time in the making.", # "id":1, # "price":19, # "title":"V is for Vengeance", # "updated_at":"2011-12-05T09:46:11Z" }, # ] # ::output-end:: # # output:: xml # # # 1 # V is for Vengeance # As with the last several books in the series, V Is for Vengeance was a long time in the making. # 19 # 2011-12-05T09:46:11Z # 2011-12-05T09:46:11Z # # #::output-end:: # # Get a list of all books in the system with pagination. Defaults to 10 per page # =end Haml Templates and styles ========================= Resource and resource method annotations are available as instance and local variables in Haml templates. Here are the listing of variables available. But the best way to understand it is to look at the default Haml templates generated by `rake rapi_doc:setup` in `config/rapi_doc` folder. A] Resource Method ------------------ @resource_name: Resource name @method_order: the numerical order of the method @content: All Misc info @url: url @access: public/privileged, etc @return: the data format of the info @params: params expected by this api @outputs: array of [output_format, output example], for example, [json, ....json output.. ] @request: example of the data expected @response: example of the response B] Resource ----------- @name: name @xml: xml representation of the resource @json: json representation @function_blocks: Array of resource method objects described above Following instance variables are only available in the index template described below (and not in the resource Haml template) @resource_methods: Array of HTML generated for each of the methods. @resource_header: HTML generated for the resource C] Index -------- resource_docs: all the resource objects, whose instance variables are described above. As mentioned before, for each resource, the HTML generated for the resource itself is available in @resource_header and HTML generated for each of its methods is available in @resource_methods array. D] Documentaton Output ---------------------- Documentation generated is located in `public/apidoc` directory. index.html: contains the HTML styles.css: CSS styles scripts.js: contains the script used to search within the documentation. Credit ====== * Based on RAPI Doc by Jaap van der Meer found here: http://code.google.com/p/rapidoc/ * https://github.com/sabman/rapi_doc