yard-restful 1.2.1 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/README.markdown +31 -22
- data/Rakefile +17 -2
- data/VERSION +1 -1
- data/lib/{yard-rest.rb → yard-restful.rb} +3 -3
- data/lib/{yard-rest → yard-restful}/html_blocks_helper.rb +0 -0
- data/lib/{yard-rest → yard-restful}/rest_filters.rb +0 -0
- data/lib/{yard-rest → yard-restful}/tags.rb +0 -0
- metadata +7 -6
data/README.markdown
CHANGED
@@ -1,22 +1,24 @@
|
|
1
1
|
# Yardoc RESTful Web Service Plugin
|
2
2
|
|
3
|
-
Previous authors: [vWorkApp](http://www.vworkapp.com), [rknLA](http://github.com/rknLA), [lsegal](http://gnuu.org/), [spape](http://github.com/spape), [DerNalia](http://github.com/DerNalia)
|
4
|
-
|
5
3
|
A plugin for [Yardoc](http://yardoc.org/) that generates documentation for RESTful web services.
|
6
4
|
|
5
|
+
Previous authors: [vWorkApp](http://www.vworkapp.com), [rknLA](http://github.com/rknLA), [lsegal](http://gnuu.org/), [spape](http://github.com/spape), [DerNalia](http://github.com/DerNalia)
|
6
|
+
|
7
7
|
## Install
|
8
|
-
Bundler will reduce your headaches
|
8
|
+
Bundler will reduce your headaches:
|
9
|
+
|
9
10
|
gem 'yard-restful' # in your gemfile
|
10
11
|
|
11
12
|
You may need to include the following dependencies as well:
|
13
|
+
|
12
14
|
gem 'redcarpet'
|
13
15
|
gem 'yard'
|
14
16
|
|
15
17
|
It also requires the Jeweler gem if you plan to use the rake build tasks.
|
16
18
|
|
17
19
|
You'll probably want to add these to your .gitignore as well
|
18
|
-
|
19
|
-
/.yardoc
|
20
|
+
|
21
|
+
/.yardoc
|
20
22
|
/public/api
|
21
23
|
|
22
24
|
So you'll have to re-genenarte your API on every machine. This should encourage more up to dateness
|
@@ -36,36 +38,48 @@ So that way, whenever you want to generate your API docs, you simply need to run
|
|
36
38
|
bundle exec yardoc
|
37
39
|
|
38
40
|
|
39
|
-
##
|
41
|
+
## Samples
|
40
42
|
|
41
|
-
[
|
43
|
+
[Full rails 3 application](http://github.com/kraft001/yard-restful-sample) with [documentation](http://kraft001.github.com/yard-restful-sample/index.html)
|
44
|
+
|
45
|
+
[Example documentation](http://kraft001.github.com/yard-restful/index.html), also [with frames](http://kraft001.github.com/yard-restful/frames.html)
|
46
|
+
|
47
|
+
[Sample controller](http://github.com/kraft001/yard-restful/blob/master/example/books_controller.rb) and [sample model](http://github.com/kraft001/yard-restful/blob/master/example/book.rb)
|
42
48
|
|
43
49
|
## Writing Comments
|
44
50
|
|
45
51
|
The following tags are provided:
|
46
52
|
|
47
53
|
- **@restful_api** version
|
54
|
+
|
48
55
|
Specifies the resource (controller) or object (model). This tag is compulsory, only **classes** and **methods** that include this in their comments are included in the API documentation.
|
49
56
|
|
50
57
|
- **@url** url
|
58
|
+
|
51
59
|
Specifies the URL which someone should use to access that resource.
|
52
60
|
|
53
61
|
- **@action** action
|
62
|
+
|
54
63
|
Specifies the http action (GET, POST, PUT etc.).
|
55
64
|
|
56
65
|
- **@required** [type] name description
|
66
|
+
|
57
67
|
Specifies an argument that must be passed to the service. You can specify as many of these as you need.
|
58
68
|
|
59
69
|
- **@optional** [type] name description
|
70
|
+
|
60
71
|
Specifies an optional argument that may be passed to the service. You can specify as many of these as you need.
|
61
72
|
|
62
73
|
- **@response** [type] description
|
74
|
+
|
63
75
|
Specifies type of the response. Usually just a link to an object.
|
64
76
|
|
65
77
|
- **@response_field** [type] name description
|
78
|
+
|
66
79
|
Further specifies the fields that are returned within the response.
|
67
80
|
|
68
81
|
- **@property** [type] name description
|
82
|
+
|
69
83
|
A property (attribute) of an object.
|
70
84
|
|
71
85
|
### Examples
|
@@ -75,42 +89,37 @@ Examples should always be together in the following order: example_request, exam
|
|
75
89
|
Markdown rendering for the text is activated if a tags text contains a newline (see example).
|
76
90
|
|
77
91
|
- **@example_request**
|
92
|
+
|
78
93
|
An example of the request that is send to the service.
|
79
94
|
|
80
95
|
- **@example_request_description**
|
96
|
+
|
81
97
|
The description text for the example request.
|
82
98
|
|
83
99
|
- **@example_response**
|
100
|
+
|
84
101
|
An example of the response that is returned from the service.
|
85
102
|
|
86
103
|
- **@example_response_description**
|
104
|
+
|
87
105
|
The description text for the example response.
|
88
106
|
|
89
107
|
- **@example**
|
108
|
+
|
90
109
|
Example of an object.
|
91
110
|
|
92
|
-
@example_response example.
|
93
|
-
```json
|
94
|
-
{
|
95
|
-
"examples": [{
|
96
|
-
"id":1,
|
97
|
-
"title":"Animals",
|
98
|
-
"text":"Dogs and cats are some.",
|
99
|
-
"highlight":true
|
100
|
-
}]
|
101
|
-
}
|
102
|
-
```
|
103
111
|
## Ignored Documentation
|
104
112
|
|
105
113
|
This plugin only documents **classes** and **methods** with **@restful_api** tag. It does not support module documentation.
|
106
114
|
|
107
|
-
## Example:
|
108
|
-
|
109
|
-
[Sample controller](http://kraft001.github.com/yard-restful-sample/app/controllers/books_controller.rb) and [sample model](http://kraft001.github.com/yard-restful-sample/app/models/book.rb)
|
110
|
-
|
111
115
|
## Development
|
112
116
|
|
113
117
|
As always, you can see what tasks are available by running:
|
114
118
|
|
115
119
|
rake -T
|
116
120
|
|
121
|
+
You can run the template locally over the included sample code by using the following rake tasks:
|
122
|
+
|
123
|
+
rake example:generate
|
124
|
+
rake example:clean
|
125
|
+
|
data/Rakefile
CHANGED
@@ -21,10 +21,25 @@ end
|
|
21
21
|
|
22
22
|
desc "Rebuild the gem from the gemspec"
|
23
23
|
task :rebuild do
|
24
|
-
gemfilename = 'yard-restful-' +
|
24
|
+
gemfilename = 'yard-restful-' + IO.read('VERSION').strip + '.gem'
|
25
25
|
`rm yard-restful-*.gem`
|
26
|
-
`gem uninstall yard-restful&& \
|
26
|
+
`gem uninstall yard-restful && \
|
27
27
|
gem build yard-restful.gemspec && \
|
28
28
|
gem install #{gemfilename}`
|
29
29
|
end
|
30
30
|
|
31
|
+
namespace :example do
|
32
|
+
desc "Generate example docs"
|
33
|
+
task :generate do
|
34
|
+
puts `yardoc -e ./lib/yard-restful.rb --title "Example Books API" --readme ./example/API_README.md --markup markdown ./example/*.rb`
|
35
|
+
# `x-www-browser ./doc/index.html`
|
36
|
+
puts 'On success open ./doc/index.html or ./doc/frames.html in your preferred browser'
|
37
|
+
end
|
38
|
+
|
39
|
+
desc "Clean example docs"
|
40
|
+
task :clean do
|
41
|
+
`rm -R doc`
|
42
|
+
`rm -R .yardoc`
|
43
|
+
puts 'Done!'
|
44
|
+
end
|
45
|
+
end
|
data/VERSION
CHANGED
@@ -1 +1 @@
|
|
1
|
-
1.2.
|
1
|
+
1.2.2
|
@@ -1,8 +1,8 @@
|
|
1
1
|
YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
|
2
2
|
|
3
|
-
require 'yard-
|
4
|
-
require 'yard-
|
5
|
-
require 'yard-
|
3
|
+
require 'yard-restful/tags'
|
4
|
+
require 'yard-restful/rest_filters'
|
5
|
+
require 'yard-restful/html_blocks_helper'
|
6
6
|
|
7
7
|
YARD::Templates::Template.extra_includes << RestFilters
|
8
8
|
YARD::Templates::Template.extra_includes << ->(opts) { HtmlBlocksHelper if opts.format == :html }
|
File without changes
|
File without changes
|
File without changes
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: yard-restful
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.2.
|
4
|
+
version: 1.2.2
|
5
5
|
prerelease:
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
@@ -9,7 +9,7 @@ authors:
|
|
9
9
|
autorequire:
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
|
-
date: 2012-10-
|
12
|
+
date: 2012-10-24 00:00:00.000000000 Z
|
13
13
|
dependencies:
|
14
14
|
- !ruby/object:Gem::Dependency
|
15
15
|
name: yard
|
@@ -37,10 +37,10 @@ extra_rdoc_files:
|
|
37
37
|
- VERSION
|
38
38
|
files:
|
39
39
|
- Rakefile
|
40
|
-
- lib/yard-
|
41
|
-
- lib/yard-
|
42
|
-
- lib/yard-
|
43
|
-
- lib/yard-
|
40
|
+
- lib/yard-restful.rb
|
41
|
+
- lib/yard-restful/html_blocks_helper.rb
|
42
|
+
- lib/yard-restful/rest_filters.rb
|
43
|
+
- lib/yard-restful/tags.rb
|
44
44
|
- templates/default/class/html/fields_list.erb
|
45
45
|
- templates/default/class/html/header.erb
|
46
46
|
- templates/default/class/html/object_details.erb
|
@@ -85,3 +85,4 @@ signing_key:
|
|
85
85
|
specification_version: 3
|
86
86
|
summary: Yardoc plugin for Restful web services
|
87
87
|
test_files: []
|
88
|
+
has_rdoc:
|