originally by vWorkApp rewritten for 0.3.0 by rknLA with substantial help from lsegal customized by spape for the MAdeK API-Documentation
A plugin for Yardoc that generates documentation for RESTful web services.
sudo gem install yard-rest
It also requires the Jeweler gem if you plan to use the rake build tasks.
Yard-Rest-Plugin and get a look to the "Example" resource.
Visit MAdeK-Api-Documetnation for a demonstration. Or visit ROR project MAdeK on github to see how we document our api.
When using yardoc you ask it to use the "rest" plugin (the --plugin option). For example:
yardoc --plugin rest --title "Our App's API" --readme "./doc/README_FOR_API"
When you want to make the API-documentation available for public use the following command:
bundle exec yardoc --plugin rest --title 'Our App's API' --readme "./doc/README_FOR_API" --output-dir ./public/api
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.8.1'
If you include yard-rest in your gemfile, you should generate docs using bundle exec:
bundle exec yardoc --plugin rest --title "Our App's API" --readme "./doc/README_FOR_API"
In addition to starting your comment with the normal RDoc description. The following tags are provided:
-
@resource resource. Specifies the resource (URL) that the service is accessed from. This tag is compulsory, only classes and methods that include this in their comments are included in the API documentation.
-
@action action. Specifies the http action (GET, POST, PUT etc.).
-
@required [type] name description. Specifies an argument that must be passed to the service. You can specify as many of these as you need.
-
@optional [type] name description. Specifies an optional argument that may be passed to the service. You can specify as many of these as you need.
-
@response_field [type] name description. Further specifies the fields that are returned within the response.
Examples should always be together in the following order: example_request, example_request_description, example_response, example_response_description (as soon as you write a example_request you need a following example_response and the other way around).
Markdown rendering for the text is activated if a tags text contains a newline (see example).
-
@example_request example. An example of the request that is send to the service.
-
@example_request_description description. The description text for the example request.
-
@example_response example. An example of the response that is returned from the service.
-
@example_response example.
{ "examples": [{ "id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true }] } -
@example_response_description example. The description text for the example response.
This plugin only documents classes and methods with @resource 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.
Both controller and methods must have @resource tags to be included in documentation.
it's a good example of how European action can produce results | some of these carpets are among the finest examples of the period.
class ExamplesController
##
# Get a collection of examples:
#
# @resource /examples
#
# @action GET
#
# @optional [Boolean] highlight Show only highlighted examples.
#
# @response_field [Array] examples The collection of examples.
# @response_field [Integer] examples[].id The id of that example.
# @response_field [String] examples[].title The title of that example.
# @response_field [String] examples[].text The text of that example.
# @response_field [String] examples[].highlight Information if the example is highlighted.
#
# @example_request {}
# @example_request_description Just requests an index of samples.
# @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}, {"id":2, "title":"Computers", "text":"Windows PC or Apple's Macintosh.", "highlight":false}]}
# @example_response_description Responds with the index of examples.
#
# @example_request {"highlight": true}
# @example_request_description Request only highlighted examples.
# @example_response
# ```json
# {
# "examples": [{
# "id":1,
# "title":"Animals",
# "text":"Dogs and cats are some.",
# "highlight":true
# }]
# }
# ```
# @example_response_description Responds only with highlighted examples.
#
def index
#...
end
##
# Get a collection of examples:
#
# @resource /examples/:id
#
# @action GET
#
# @required [Integer] id The id of the example.
#
# @response_field [Integer] example.id The id of that example.
# @response_field [String] example.title The title of that example.
# @response_field [String] example.text The text of that example.
# @response_field [String] example.highlight Information if the example is highlighted.
#
# @example_request {"id":1}
# @example_request_description Just requests the example with id 1.
# @example_response
# ```json
# {
# "example": {
# "id":1,
# "title":"Animals",
# "text":"Dogs and cats are some.",
# "highlight":true
# }
# }
# ```
# @example_response_description Responds with the requested example.
#
def show
#...
end
##
# Create an example:
#
# @resource /examples
#
# @action POST
#
# @required [Hash] example The object of the new example.
# @required [String] example.title The title of the new example.
# @required [String] example.text The text of the new example.
#
# @optional [Boolean] example.highlight The highlight status of the new example. (Default is false)
#
# @example_request {"example": {"title":"Fish", "text": "Angel- or Butterflyfish"}}
# @example_resuest_description Create a new example for fish.
# @example_response {}
# @example_response_description Responds with an empty hash and status: 201 (Created).
#
def create
#...
end
end
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