yard-rest 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- data/README.markdown +165 -0
- data/Rakefile +42 -0
- data/VERSION +1 -0
- data/example/app/controllers/examples_controller.rb +80 -0
- data/lib/yard-rest/rest_filters.rb +21 -0
- data/lib/yard-rest/tags.rb +16 -0
- data/lib/yard-rest.rb +6 -0
- metadata +73 -0
data/README.markdown
ADDED
@@ -0,0 +1,165 @@
|
|
1
|
+
# Yardoc RESTful Web Service Plugin
|
2
|
+
|
3
|
+
originally by [vWorkApp](http://www.vworkapp.com)
|
4
|
+
rewritten for 0.3.0 by [rknLA](http://github.com/rknLA) with substantial help from [lsegal](http://gnuu.org/)
|
5
|
+
customized by [spape](http://github.com/spape) for the [MAdeK](http://github.com/zhdk/madek) API-Documentation
|
6
|
+
|
7
|
+
A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTful web services.
|
8
|
+
|
9
|
+
## Install
|
10
|
+
sudo gem install yard-rest
|
11
|
+
|
12
|
+
It also requires the Jeweler gem if you plan to use the rake build tasks.
|
13
|
+
|
14
|
+
## Generating Docs
|
15
|
+
|
16
|
+
When using yardoc you ask it to use the "rest" plugin (the --plugin option). For example:
|
17
|
+
|
18
|
+
yardoc --plugin rest --title "Our App's API" --readme "./doc/README_FOR_API"
|
19
|
+
|
20
|
+
## Gemfile functionality
|
21
|
+
|
22
|
+
You may also include yard-rest in your gemfile using:
|
23
|
+
|
24
|
+
gem 'yard-rest'
|
25
|
+
|
26
|
+
You may need to include the following dependencies as well:
|
27
|
+
|
28
|
+
gem 'redcarpet'
|
29
|
+
gem 'yard', '~>0.7.4'
|
30
|
+
|
31
|
+
If you include yard-rest in your gemfile, you should generate docs using bundle exec:
|
32
|
+
|
33
|
+
bundle exec yardoc --plugin rest --title "Our App's API" --readme "./doc/README_FOR_API"
|
34
|
+
|
35
|
+
## Writing Comments
|
36
|
+
|
37
|
+
In addition to starting your comment with the normal RDoc description. The following tags are provided:
|
38
|
+
|
39
|
+
- @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.
|
40
|
+
|
41
|
+
- @action action. Specifies the http action (GET, POST, PUT etc.).
|
42
|
+
|
43
|
+
- @required [type] name description. Specifies an argument that must be passed to the service. You can specify as many of these as you need.
|
44
|
+
|
45
|
+
- @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.
|
46
|
+
|
47
|
+
- @response_field [type] name description. Further specifies the fields that are returned within the response.
|
48
|
+
|
49
|
+
### Examples
|
50
|
+
|
51
|
+
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).
|
52
|
+
|
53
|
+
- @example_request example. An example of the request that is send to the service.
|
54
|
+
|
55
|
+
- @example_request_description description. The description text for the example request.
|
56
|
+
|
57
|
+
- @example_response example. An example of the response that is returned from the service.
|
58
|
+
|
59
|
+
- @example_response_description example. The description text for the example response.
|
60
|
+
|
61
|
+
|
62
|
+
## Ignored Documentation
|
63
|
+
|
64
|
+
This plugin only documents **classes** and **methods** with **@resource** tags. It does not support module documentation.
|
65
|
+
|
66
|
+
The rationale here is that you are documenting external services (as represented by controllers and methods), and not internal code.
|
67
|
+
|
68
|
+
Both controller *and* methods must have @resource tags to be included in documentation.
|
69
|
+
|
70
|
+
## Example:
|
71
|
+
|
72
|
+
##
|
73
|
+
# A thing characteristic of its kind or illustrating a general rule:
|
74
|
+
# it's a good example of how European action can produce results | some of these carpets are among the finest examples of the period.
|
75
|
+
#
|
76
|
+
class ExamplesController
|
77
|
+
|
78
|
+
##
|
79
|
+
# Get a collection of examples:
|
80
|
+
#
|
81
|
+
# @resource /examples
|
82
|
+
#
|
83
|
+
# @action GET
|
84
|
+
#
|
85
|
+
# @optional [Boolean] highlight Show only highlighted examples.
|
86
|
+
#
|
87
|
+
# @response_field [Array] examples The collection of examples.
|
88
|
+
# @response_field [Integer] examples[].id The id of that example.
|
89
|
+
# @response_field [String] examples[].title The title of that example.
|
90
|
+
# @response_field [String] examples[].text The text of that example.
|
91
|
+
# @response_field [String] examples[].highlight Information if the example is highlighted.
|
92
|
+
#
|
93
|
+
# @example_request {}
|
94
|
+
# @example_request_description Just requests an index of samples.
|
95
|
+
# @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}]}
|
96
|
+
# @example_response_description Responds with the index of examples.
|
97
|
+
#
|
98
|
+
# @example_request {"highlight": true}
|
99
|
+
# @example_request_description Request only highlighted examples.
|
100
|
+
# @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}]}
|
101
|
+
# @example_response_description Responds only with highlighted examples.
|
102
|
+
#
|
103
|
+
def index
|
104
|
+
#...
|
105
|
+
end
|
106
|
+
|
107
|
+
##
|
108
|
+
# Get a collection of examples:
|
109
|
+
#
|
110
|
+
# @resource /examples/:id
|
111
|
+
#
|
112
|
+
# @action GET
|
113
|
+
#
|
114
|
+
# @required [Integer] id The id of the example.
|
115
|
+
#
|
116
|
+
# @response_field [Integer] example.id The id of that example.
|
117
|
+
# @response_field [String] example.title The title of that example.
|
118
|
+
# @response_field [String] example.text The text of that example.
|
119
|
+
# @response_field [String] example.highlight Information if the example is highlighted.
|
120
|
+
#
|
121
|
+
# @example_request {"id":1}
|
122
|
+
# @example_request_description Just requests the example with id 1.
|
123
|
+
# @example_response {"example": {"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}}
|
124
|
+
# @example_response_description Responds with the requested example.
|
125
|
+
#
|
126
|
+
def show
|
127
|
+
#...
|
128
|
+
end
|
129
|
+
|
130
|
+
##
|
131
|
+
# Create an example:
|
132
|
+
#
|
133
|
+
# @resource /examples
|
134
|
+
#
|
135
|
+
# @action POST
|
136
|
+
#
|
137
|
+
# @required [Hash] example The object of the new example.
|
138
|
+
# @required [String] example.title The title of the new example.
|
139
|
+
# @required [String] example.text The text of the new example.
|
140
|
+
#
|
141
|
+
# @optional [Boolean] example.highlight The highlight status of the new example. (Default is false)
|
142
|
+
#
|
143
|
+
# @example_request {"example": {"title":"Fish", "text": "Angel- or Butterflyfish"}}
|
144
|
+
# @example_resuest_description Create a new example for fish.
|
145
|
+
# @example_response {}
|
146
|
+
# @example_response_description Responds with an empty hash and status: 201 (Created).
|
147
|
+
#
|
148
|
+
def create
|
149
|
+
#...
|
150
|
+
end
|
151
|
+
end
|
152
|
+
|
153
|
+
## Development
|
154
|
+
|
155
|
+
As always, you can see what tasks are available by running:
|
156
|
+
|
157
|
+
rake -T
|
158
|
+
|
159
|
+
You can run the template locally over the included sample code by using the following rake tasks:
|
160
|
+
|
161
|
+
rake ex:clean
|
162
|
+
rake ex:generate
|
163
|
+
|
164
|
+
|
165
|
+
|
data/Rakefile
ADDED
@@ -0,0 +1,42 @@
|
|
1
|
+
require 'rubygems'
|
2
|
+
require 'rake'
|
3
|
+
|
4
|
+
begin
|
5
|
+
require 'jeweler'
|
6
|
+
Jeweler::Tasks.new do |gem|
|
7
|
+
gem.name = "yard-rest"
|
8
|
+
gem.summary = %Q{A customized plugin for Yardoc that produces API documentation for Restful web services}
|
9
|
+
gem.description = %Q{A plugin for Yardoc that produces API documentation for Restful web services. See README.markdown for more details}
|
10
|
+
gem.email = ''
|
11
|
+
gem.homepage = "https://github.com/spape/yard-rest-plugin"
|
12
|
+
gem.authors = ['R. Kevin Nelson', 'Aisha Fenton', 'Sebastian Pape']
|
13
|
+
gem.add_dependency("yard", '~>0.7.4')
|
14
|
+
gem.files = Dir.glob("{lib,example,templates/rest}/**/*.*").concat(["Rakefile"])
|
15
|
+
gem.extra_rdoc_files = ['VERSION', 'README.markdown']
|
16
|
+
end
|
17
|
+
Jeweler::GemcutterTasks.new
|
18
|
+
rescue LoadError
|
19
|
+
puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
|
20
|
+
end
|
21
|
+
|
22
|
+
desc "Rebuild the gem from the gemspec"
|
23
|
+
task :rebuild do
|
24
|
+
gemfilename = 'yard-rest-' + File.open('VERSION').gets.strip + '.gem'
|
25
|
+
`rm yard-rest-*.gem`
|
26
|
+
`gem uninstall yard-rest&& \
|
27
|
+
gem build yard-rest.gemspec && \
|
28
|
+
gem install #{gemfilename}`
|
29
|
+
end
|
30
|
+
|
31
|
+
namespace :ex do
|
32
|
+
desc "Generate example docs"
|
33
|
+
task :generate do
|
34
|
+
`yardoc 'example/*.rb' --backtrace -e ./lib/yard-rest.rb -r example/README.markdown --title 'Sample API'`
|
35
|
+
end
|
36
|
+
|
37
|
+
desc "Clean example docs"
|
38
|
+
task :clean do
|
39
|
+
`rm -R doc`
|
40
|
+
`rm -R .yardoc`
|
41
|
+
end
|
42
|
+
end
|
data/VERSION
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
1.0.0
|
@@ -0,0 +1,80 @@
|
|
1
|
+
##
|
2
|
+
# A thing characteristic of its kind or illustrating a general rule:
|
3
|
+
# it's a good example of how European action can produce results | some of these carpets are among the finest examples of the period.
|
4
|
+
#
|
5
|
+
class ExamplesController
|
6
|
+
|
7
|
+
##
|
8
|
+
# Get a collection of examples:
|
9
|
+
#
|
10
|
+
# @resource /examples
|
11
|
+
#
|
12
|
+
# @action GET
|
13
|
+
#
|
14
|
+
# @optional [Boolean] highlight Show only highlighted examples.
|
15
|
+
#
|
16
|
+
# @response_field [Array] examples The collection of examples.
|
17
|
+
# @response_field [Integer] examples[].id The id of that example.
|
18
|
+
# @response_field [String] examples[].title The title of that example.
|
19
|
+
# @response_field [String] examples[].text The text of that example.
|
20
|
+
# @response_field [String] examples[].highlight Information if the example is highlighted.
|
21
|
+
#
|
22
|
+
# @example_request {}
|
23
|
+
# @example_request_description Just requests an index of samples.
|
24
|
+
# @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}]}
|
25
|
+
# @example_response_description Responds with the index of examples.
|
26
|
+
#
|
27
|
+
# @example_request {"highlight": true}
|
28
|
+
# @example_request_description Request only highlighted examples.
|
29
|
+
# @example_response {"examples": [{"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}]}
|
30
|
+
# @example_response_description Responds only with highlighted examples.
|
31
|
+
#
|
32
|
+
def index
|
33
|
+
#...
|
34
|
+
end
|
35
|
+
|
36
|
+
##
|
37
|
+
# Get a collection of examples:
|
38
|
+
#
|
39
|
+
# @resource /examples/:id
|
40
|
+
#
|
41
|
+
# @action GET
|
42
|
+
#
|
43
|
+
# @required [Integer] id The id of the example.
|
44
|
+
#
|
45
|
+
# @response_field [Integer] example.id The id of that example.
|
46
|
+
# @response_field [String] example.title The title of that example.
|
47
|
+
# @response_field [String] example.text The text of that example.
|
48
|
+
# @response_field [String] example.highlight Information if the example is highlighted.
|
49
|
+
#
|
50
|
+
# @example_request {"id":1}
|
51
|
+
# @example_request_description Just requests the example with id 1.
|
52
|
+
# @example_response {"example": {"id":1, "title":"Animals", "text":"Dogs and cats are some.", "highlight":true}}
|
53
|
+
# @example_response_description Responds with the requested example.
|
54
|
+
#
|
55
|
+
def show
|
56
|
+
#...
|
57
|
+
end
|
58
|
+
|
59
|
+
##
|
60
|
+
# Create an example:
|
61
|
+
#
|
62
|
+
# @resource /examples
|
63
|
+
#
|
64
|
+
# @action POST
|
65
|
+
#
|
66
|
+
# @required [Hash] example The object of the new example.
|
67
|
+
# @required [String] example.title The title of the new example.
|
68
|
+
# @required [String] example.text The text of the new example.
|
69
|
+
#
|
70
|
+
# @optional [Boolean] example.highlight The highlight status of the new example. (Default is false)
|
71
|
+
#
|
72
|
+
# @example_request {"example": {"title":"Fish", "text": "Angel- or Butterflyfish"}}
|
73
|
+
# @example_resuest_description Create a new example for fish.
|
74
|
+
# @example_response {}
|
75
|
+
# @example_response_description Responds with an empty hash and status: 201 (Created).
|
76
|
+
#
|
77
|
+
def create
|
78
|
+
#...
|
79
|
+
end
|
80
|
+
end
|
@@ -0,0 +1,21 @@
|
|
1
|
+
module RestFilters
|
2
|
+
|
3
|
+
def index_objects(list)
|
4
|
+
list = reject_without_resource(list)
|
5
|
+
list
|
6
|
+
end
|
7
|
+
|
8
|
+
def reject_without_resource(list)
|
9
|
+
list.delete_if { |object|
|
10
|
+
if [:class].include?(object.type)
|
11
|
+
object.meths.detect{|x| x.has_tag? :resource}.nil?
|
12
|
+
else
|
13
|
+
true
|
14
|
+
end
|
15
|
+
}
|
16
|
+
end
|
17
|
+
|
18
|
+
end
|
19
|
+
|
20
|
+
|
21
|
+
|
@@ -0,0 +1,16 @@
|
|
1
|
+
# Define custom tags
|
2
|
+
YARD::Tags::Library.define_tag("URL for the Resource", :resource)
|
3
|
+
YARD::Tags::Library.define_tag("HTTP-Action for the Resource", :action)
|
4
|
+
|
5
|
+
YARD::Tags::Library.define_tag("Required Arguments", :required, :with_types_and_name)
|
6
|
+
YARD::Tags::Library.define_tag("Optional Arguments", :optional, :with_types_and_name)
|
7
|
+
|
8
|
+
YARD::Tags::Library.define_tag("Example Request", :example_request)
|
9
|
+
YARD::Tags::Library.define_tag("Example Request Description", :example_request_description)
|
10
|
+
YARD::Tags::Library.define_tag("Request Fields", :request_field, :with_types_and_name)
|
11
|
+
|
12
|
+
YARD::Tags::Library.define_tag("Example Response", :example_response)
|
13
|
+
YARD::Tags::Library.define_tag("Example Response Description", :example_response_description)
|
14
|
+
YARD::Tags::Library.define_tag("Response Fields", :response_field, :with_types_and_name)
|
15
|
+
|
16
|
+
YARD::Tags::Library.define_tag("Headers", :header, :with_name)
|
data/lib/yard-rest.rb
ADDED
@@ -0,0 +1,6 @@
|
|
1
|
+
YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
|
2
|
+
|
3
|
+
require File.join(File.dirname(__FILE__), 'yard-rest', 'tags')
|
4
|
+
require File.join(File.dirname(__FILE__), 'yard-rest', 'rest_filters')
|
5
|
+
|
6
|
+
YARD::Templates::Template.extra_includes << RestFilters
|
metadata
ADDED
@@ -0,0 +1,73 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: yard-rest
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 1.0.0
|
5
|
+
prerelease:
|
6
|
+
platform: ruby
|
7
|
+
authors:
|
8
|
+
- R. Kevin Nelson
|
9
|
+
- Aisha Fenton
|
10
|
+
- Sebastian Pape
|
11
|
+
autorequire:
|
12
|
+
bindir: bin
|
13
|
+
cert_chain: []
|
14
|
+
date: 2012-04-30 00:00:00.000000000 Z
|
15
|
+
dependencies:
|
16
|
+
- !ruby/object:Gem::Dependency
|
17
|
+
name: yard
|
18
|
+
requirement: !ruby/object:Gem::Requirement
|
19
|
+
none: false
|
20
|
+
requirements:
|
21
|
+
- - ~>
|
22
|
+
- !ruby/object:Gem::Version
|
23
|
+
version: 0.7.4
|
24
|
+
type: :runtime
|
25
|
+
prerelease: false
|
26
|
+
version_requirements: !ruby/object:Gem::Requirement
|
27
|
+
none: false
|
28
|
+
requirements:
|
29
|
+
- - ~>
|
30
|
+
- !ruby/object:Gem::Version
|
31
|
+
version: 0.7.4
|
32
|
+
description: A plugin for Yardoc that produces API documentation for Restful web services.
|
33
|
+
See README.markdown for more details
|
34
|
+
email: ''
|
35
|
+
executables: []
|
36
|
+
extensions: []
|
37
|
+
extra_rdoc_files:
|
38
|
+
- README.markdown
|
39
|
+
- VERSION
|
40
|
+
files:
|
41
|
+
- Rakefile
|
42
|
+
- example/app/controllers/examples_controller.rb
|
43
|
+
- lib/yard-rest.rb
|
44
|
+
- lib/yard-rest/rest_filters.rb
|
45
|
+
- lib/yard-rest/tags.rb
|
46
|
+
- README.markdown
|
47
|
+
- VERSION
|
48
|
+
homepage: https://github.com/spape/yard-rest-plugin
|
49
|
+
licenses: []
|
50
|
+
post_install_message:
|
51
|
+
rdoc_options: []
|
52
|
+
require_paths:
|
53
|
+
- lib
|
54
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
55
|
+
none: false
|
56
|
+
requirements:
|
57
|
+
- - ! '>='
|
58
|
+
- !ruby/object:Gem::Version
|
59
|
+
version: '0'
|
60
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
61
|
+
none: false
|
62
|
+
requirements:
|
63
|
+
- - ! '>='
|
64
|
+
- !ruby/object:Gem::Version
|
65
|
+
version: '0'
|
66
|
+
requirements: []
|
67
|
+
rubyforge_project:
|
68
|
+
rubygems_version: 1.8.21
|
69
|
+
signing_key:
|
70
|
+
specification_version: 3
|
71
|
+
summary: A customized plugin for Yardoc that produces API documentation for Restful
|
72
|
+
web services
|
73
|
+
test_files: []
|