Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A plugin for Yardoc that produces API documentation for Restful web services
Ruby JavaScript

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
example
lib
templates/rest
.gitignore
README.markdown
Rakefile
VERSION
yard-rest-plugin.gemspec

README.markdown

Yardoc RESTful Web Service Plugin

by VisFleet

A plugin for Yardoc that generates documentation for RESTful web services.

Install

sudo gem install yard-rest-plugin

It also requires the Jeweler gem if you plan to use the rake build tasks.

Generating Docs

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"

Writing Comments

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_request example. An example of the request that is send to the service

  • @request_field name description. Further specifies the fields that are send within the request

  • @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

Ignored Documentation

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.

Example:

##
# Retuns all samples, as XML, for the current user that match the given parameters.
# 
# @url [GET] /samples.[format]?[arguments]
# @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 samples 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>
#     </sample>
#   <samples>
# 
# @response_field [Integer] id A unique ID identifying the Sample
# @response_field [String] name The name of the sample
# @response_field [String] state The current status of the Sample. Can be complete, uncomplete, etc.
# @response_field [String] notes Any notes given for the sample
# @response_field [DateTime] updated_at The Date/Time (in ISO8601) that the Sample was last updated
# @response_field [DateTime] created_at The Date/Time (in ISO8601) that the Sample was created
# 
def index
end

##
# Retuns all samples, as XML, for the current user that match the given parameters.
# 
# @url [POST] /samples.[format]?[arguments]
# 
# @argument [String] format Only "xml" is support at this time.
#
# @example_request
#   <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>
#     <note_attributes type="array">
#       <note>
#         <id>new_123</id>
#         <text>Note One</note>
#       </note>
#     </note_attributes>
#     <updated_at type="datetime">2010-03-09T20:43:29Z</updated_at>
#     <created_at type="datetime">2010-03-09T20:43:16Z</created_at>
#   </sample>
#
# @request_field [Integer] id A unique ID identifying the Sample
# @request_field [String] name The name of the sample
# @request_field [String] state The current status of the Sample. Can be complete, uncomplete, etc.
# @request_field [String] note_attributes Any notes given for the sample that will be created
# @request_field [DateTime] updated_at The Date/Time (in ISO8601) that the Sample was last updated
# @request_field [DateTime] created_at The Date/Time (in ISO8601) that the Sample was created
#
# @example_response
#   <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 type="array">
#       <note>
#         <text>Note One</note>
#       </note>
#     </notes>
#     <updated_at type="datetime">2010-03-09T20:43:29Z</updated_at>
#     <created_at type="datetime">2010-03-09T20:43:16Z</created_at>
#   </sample>
# 
# @response_field [Integer] id A unique ID identifying the Sample
# @response_field [String] name The name of the sample
# @response_field [String] state The current status of the Sample. Can be complete, uncomplete, etc.
# @response_field [String] notes Any notes given for the sample
# @response_field [DateTime] updated_at The Date/Time (in ISO8601) that the Sample was last updated
# @response_field [DateTime] created_at The Date/Time (in ISO8601) that the Sample was created
#
def create
end

Development

You can run the template locally over the included sample code by using the following rake tasks:

rake ex:clean
rake ex:generate
Something went wrong with that request. Please try again.