Skip to content
A plugin for Yardoc that produces API documentation for Restful web services
Ruby JavaScript
Find file
#1 Compare This branch is 61 commits ahead of visfleet:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
example
lib
templates/default
.gitignore
README.markdown
Rakefile
VERSION
yard-rest.gemspec

README.markdown

Yardoc RESTful Web Service Plugin

originally by vWorkApp rewritten for 0.3.0 by rknLA with substantial help from lsegal

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

Install

sudo gem install yard-rest

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" plugin (the --plugin option). For example:

yardoc '*.rb' --plugin rest --title "Our App's API"

Gemfile functionality

You may also include yard-rest in your gemfile using:

gem 'yard-rest'

You may need to include the following dependencies as well:

gem 'redcarpet'
gem 'yard', '~>0.7.4'

If you include yard-rest in your gemfile, you should generate docs using bundle exec:

bundle exec yardoc '*.rb' --plugin 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.

  • @required_argument [type] name description. Specifies an argument that must be passed to the service. You can specify as many of these as you need.

  • @optional_argument [type] name description. Specifies an optional argument that may be passed to the service. You can specify as many of these as you need.

  • @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. This is useful when the service accepts only one argument that has many fields, like a JSON or XML string.

  • @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]
# 
# @required_argument [String] format Only "xml" is support at this time.
# @required_argument [String] name The name of the sample
# @required_argument [String] resource The resource that sample belongs to
# @optional_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]
# 
# @required_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

As always, you can see what tasks are available by running:

rake -T

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.