Yardoc RESTful Web Service Plugin
A plugin for Yardoc that generates documentation for RESTful web services.
sudo gem install yard-rest-plugin
It also requires the Jeweler gem if you plan to use the rake build tasks.
When using yardoc you ask it to use the "rest" template (the -t option). For example:
yardoc '*.rb' -t rest --title "Our App's API"
In addition to starting your comment with the normal RDoc description. The following tags are provided:
@url url. Specifies the URL that the service is accessed from. This tag is compulsory, only classes and methods that include this in their comments are included.
@topic topic. Specifies the topic to categorise a class (not a method) under.
@argument [type] name description. Specifies an argument that is passed to the service. You can specify as many of these as required
@example_response example. An example of the response that is returned from the service
@response_field name description. Further specifies the fields that are returned within the response
This plugin only documents classes and methods with @url tags. It does not support module documentation.
The rationale here is that you are documenting external services (as represented by controllers and methods), and not internal code.
## # Retuns all samples, as XML, for the current user that match the given parameters. # # @url # [GET] /samples/index.[format]?[arguments] # # @argument [String] format Only "xml" is support at this time. # @argument [String] name The name of the sample # @argument [String] reource The resource that sample belongs to # @argument ["@assigned"|"@complete"|"!@complete"] search Return jobs that are assigned, complete, or # uncomplete. # # @example_response # <samples type="array"> # <sample> # <id>961</id> # <name>My Sample</name> # <state>complete</state> # <last_unassigned_user_id type="integer"></last_unassigned_user_id> # <resource_id type="integer">127</resource_id> # <notes></notes> # <updated_at type="datetime">2010-03-09T20:43:29Z</updated_at> # <created_at type="datetime">2010-03-09T20:43:16Z</created_at> # </interval> # <intervals> # # @response_field id A unique ID identifying the Sample # @response_field name The name of the sample # @response_field state The current status of the Sample. Can be complete, uncomplete, etc. # @response_field notes Any notes given for the sample # @response_field updated_at The Date/Time (in ISO8601) that the Sample was last updated # @response_field created_at The Date/Time (in ISO8601) that the Sample was created # def index end
You can run the template locally over the included sample code by using the following rake tasks:
rake ex:clean rake ex:generate