rapidoc 0.0.6 → 0.0.7
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +2 -0
- data/.rspec +1 -0
- data/README.rdoc +11 -2
- data/lib/rapidoc.rb +23 -8
- data/lib/rapidoc/action_doc.rb +8 -6
- data/lib/rapidoc/config.rb +3 -3
- data/lib/rapidoc/http_response.rb +3 -1
- data/lib/rapidoc/resource_doc.rb +2 -2
- data/lib/rapidoc/resources_extractor.rb +1 -1
- data/lib/rapidoc/templates/action.html.hbs +34 -11
- data/lib/rapidoc/templates/index.html.hbs +4 -3
- data/lib/rapidoc/templates_generator.rb +8 -2
- data/lib/rapidoc/version.rb +1 -1
- data/lib/rapidoc/yaml_parser.rb +4 -4
- data/lib/tasks/rapidoc.rake +15 -6
- data/rapidoc.gemspec +6 -5
- data/spec/dummy/config/application.rb +0 -1
- data/spec/dummy/config/environments/development.rb +68 -25
- data/spec/dummy/config/environments/production.rb +41 -28
- data/spec/dummy/config/environments/test.rb +67 -24
- data/spec/dummy/config/routes.rb +2 -2
- data/spec/features/action_spec.rb +9 -8
- data/spec/features/index_spec.rb +3 -3
- data/spec/lib/action_doc_spec.rb +8 -6
- data/spec/lib/config_spec.rb +11 -7
- data/spec/lib/controller_extractor_spec.rb +4 -1
- data/spec/lib/http_response_spec.rb +1 -1
- data/spec/lib/param_errors_spec.rb +5 -0
- data/spec/lib/rake_spec.rb +74 -13
- data/spec/lib/rapidoc_spec.rb +31 -36
- data/spec/lib/resource_doc_spec.rb +5 -1
- data/spec/lib/resources_extractor_spec.rb +6 -0
- data/spec/lib/templates_generator_spec.rb +5 -4
- metadata +25 -43
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 19849b869a7892e7201a4eb86c4b72cac46d99dd
|
4
|
+
data.tar.gz: 49e69db36a4e329cf25413d758e0ecc980c2611b
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 8992fc2d53b76afe72ffe258b6ce7431b81c743e9eddde3d80e931a234c1e4b84c36a927ff959eb8584ab986106e60dddee9e6bc68e85b479bebfe8112fa0bfe
|
7
|
+
data.tar.gz: 5a9ca90ce4ce17ed9dd7c2cfad814e0b94b6c28eba77c76afcdde43a7f7a71522a9956113d38dec2875b93b9aac8c2683eeb4bc41db62b4fccbf3141abfd3733
|
data/.gitignore
CHANGED
data/.rspec
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
--color
|
data/README.rdoc
CHANGED
@@ -1,6 +1,6 @@
|
|
1
1
|
= Rapidoc
|
2
2
|
|
3
|
-
REST API documentation generator for rails projects ( 0.
|
3
|
+
REST API documentation generator for rails projects ( 0.07 version ).
|
4
4
|
|
5
5
|
This gem let you generate API documentation of your rails project in html format.
|
6
6
|
It uses routes information, rapidoc comments and json examples for generate
|
@@ -17,10 +17,14 @@ Add this line to your application's Gemfile:
|
|
17
17
|
|
18
18
|
gem 'rapidoc'
|
19
19
|
|
20
|
-
|
20
|
+
Then execute:
|
21
21
|
|
22
22
|
$ bundle
|
23
23
|
|
24
|
+
And finally, run:
|
25
|
+
|
26
|
+
rake rapidoc:install
|
27
|
+
|
24
28
|
== Usage
|
25
29
|
|
26
30
|
For generate documentation run:
|
@@ -129,6 +133,11 @@ For more details and options please visit the Wiki[https://github.com/drinor/rap
|
|
129
133
|
|
130
134
|
* Simple and intuitive navigation.
|
131
135
|
|
136
|
+
== Contributors
|
137
|
+
|
138
|
+
* harchs[https://github.com/harchs]
|
139
|
+
* ljrzarate[https://github.com/ljrzarate]
|
140
|
+
|
132
141
|
== Contributing
|
133
142
|
|
134
143
|
1. Fork it
|
data/lib/rapidoc.rb
CHANGED
@@ -21,15 +21,30 @@ module Rapidoc
|
|
21
21
|
|
22
22
|
METHODS = [ "GET", "PUT", "DELETE", "POST" ]
|
23
23
|
|
24
|
-
def
|
25
|
-
# should be done in this order
|
26
|
-
FileUtils.mkdir target_dir unless File.directory? target_dir
|
27
|
-
FileUtils.mkdir actions_dir unless File.directory? actions_dir
|
24
|
+
def create_config_structure
|
28
25
|
FileUtils.cp_r GEM_CONFIG_DIR + "/.", config_dir unless File.directory? config_dir
|
29
|
-
FileUtils.cp_r GEM_ASSETS_DIR, target_dir
|
30
26
|
FileUtils.mkdir examples_dir unless File.directory? examples_dir
|
31
27
|
end
|
32
28
|
|
29
|
+
def create_doc_structure
|
30
|
+
FileUtils.mkdir_p target_dir unless File.directory? target_dir
|
31
|
+
FileUtils.mkdir_p actions_dir unless File.directory? actions_dir
|
32
|
+
FileUtils.cp_r GEM_ASSETS_DIR, target_dir
|
33
|
+
end
|
34
|
+
|
35
|
+
def create_folders_for_file(file)
|
36
|
+
route_dir = file.split("/")
|
37
|
+
route_dir.pop
|
38
|
+
route_dir = route_dir.join("/")
|
39
|
+
FileUtils.mkdir route_dir unless File.directory? route_dir
|
40
|
+
end
|
41
|
+
|
42
|
+
def create_folders_for_files(files)
|
43
|
+
files.each do |file|
|
44
|
+
create_folders_for_file file
|
45
|
+
end
|
46
|
+
end
|
47
|
+
|
33
48
|
def remove_structure
|
34
49
|
remove_doc
|
35
50
|
remove_config
|
@@ -40,12 +55,13 @@ module Rapidoc
|
|
40
55
|
end
|
41
56
|
|
42
57
|
def remove_doc
|
43
|
-
FileUtils.rm_r
|
58
|
+
FileUtils.rm_r "#{::Rails.root}/public/docs" if File.directory? "#{::Rails.root}/public/docs"
|
44
59
|
end
|
45
60
|
|
46
61
|
def reset_structure
|
47
62
|
remove_structure
|
48
|
-
|
63
|
+
create_config_structure
|
64
|
+
create_doc_structure
|
49
65
|
end
|
50
66
|
|
51
67
|
def remove_examples
|
@@ -54,7 +70,6 @@ module Rapidoc
|
|
54
70
|
|
55
71
|
def generate_doc
|
56
72
|
resources_doc = get_resources
|
57
|
-
|
58
73
|
generate_index_template( resources_doc )
|
59
74
|
generate_actions_templates( resources_doc )
|
60
75
|
end
|
data/lib/rapidoc/action_doc.rb
CHANGED
@@ -10,8 +10,8 @@ module Rapidoc
|
|
10
10
|
#
|
11
11
|
class ActionDoc
|
12
12
|
attr_reader :resource, :urls, :action, :action_method, :description,
|
13
|
-
:response_formats, :authentication, :params, :file, :http_responses,
|
14
|
-
:errors, :example_res, :example_req
|
13
|
+
:response_formats, :authentication, :params, :headers, :file, :http_responses,
|
14
|
+
:errors, :example_res, :example_req, :resource_name
|
15
15
|
|
16
16
|
##
|
17
17
|
# @param resource [String] resource name
|
@@ -19,11 +19,12 @@ module Rapidoc
|
|
19
19
|
# @param urls [Array] all urls that call this method
|
20
20
|
#
|
21
21
|
def initialize( routes_info, controller_info, examples_route )
|
22
|
+
@resource_name = routes_info[:resource].split('/').last
|
22
23
|
@resource = routes_info[:resource].to_s
|
23
24
|
@action = routes_info[:action].to_s
|
24
25
|
@action_method = routes_info[:method].to_s || '-----'
|
25
26
|
@urls = routes_info[:urls]
|
26
|
-
@file = @resource + '
|
27
|
+
@file = @resource + '/' + @action
|
27
28
|
|
28
29
|
puts " - Generating #{@action} action documentation..." if trace?
|
29
30
|
|
@@ -43,6 +44,7 @@ module Rapidoc
|
|
43
44
|
@description = controller_info["description"]
|
44
45
|
@response_formats = default_response_formats || controller_info["response_formats"]
|
45
46
|
@params = controller_info["params"]
|
47
|
+
@headers = controller_info["headers"]
|
46
48
|
@http_responses = get_http_responses controller_info["http_responses"]
|
47
49
|
@errors = controller_info["errors"] ? controller_info["errors"].dup : []
|
48
50
|
@authentication = get_authentication controller_info["authentication_required"]
|
@@ -50,7 +52,7 @@ module Rapidoc
|
|
50
52
|
end
|
51
53
|
|
52
54
|
def get_authentication( required_authentication )
|
53
|
-
if [ true, false ].include? required_authentication
|
55
|
+
if [ true, false ].include? required_authentication
|
54
56
|
required_authentication
|
55
57
|
else
|
56
58
|
default_authentication
|
@@ -75,14 +77,14 @@ module Rapidoc
|
|
75
77
|
end
|
76
78
|
|
77
79
|
def load_request( examples_route )
|
78
|
-
file = examples_route + '/' + @resource + '
|
80
|
+
file = examples_route + '/' + @resource + '/' + @action + '_request.json'
|
79
81
|
return unless File.exists?( file )
|
80
82
|
puts " + Loading request examples..." if trace?
|
81
83
|
File.open( file ){ |f| @example_req = JSON.pretty_generate( JSON.parse(f.read) ) }
|
82
84
|
end
|
83
85
|
|
84
86
|
def load_response( examples_route )
|
85
|
-
file = examples_route + '/' + @resource + '
|
87
|
+
file = examples_route + '/' + @resource + '/' + @action + '_response.json'
|
86
88
|
return unless File.exists?( file )
|
87
89
|
puts " + Loading response examples..." if trace?
|
88
90
|
File.open( file ){ |f| @example_res = JSON.pretty_generate( JSON.parse(f.read) ) }
|
data/lib/rapidoc/config.rb
CHANGED
@@ -80,7 +80,7 @@ module Rapidoc
|
|
80
80
|
if File.exists?( config_file_path )
|
81
81
|
form_file_name( target_dir_from_config, f )
|
82
82
|
else
|
83
|
-
form_file_name( File.join( ::Rails.root.to_s, '
|
83
|
+
form_file_name( File.join( ::Rails.root.to_s, 'public/docs' ), f )
|
84
84
|
end
|
85
85
|
end
|
86
86
|
|
@@ -110,9 +110,9 @@ module Rapidoc
|
|
110
110
|
|
111
111
|
def target_dir_from_config
|
112
112
|
if @@config and @@config.has_key?( "doc_route" )
|
113
|
-
File.join(::Rails.root.to_s, @@config['doc_route'] )
|
113
|
+
File.join(::Rails.root.to_s, "public/docs/#{@@config['doc_route']}" )
|
114
114
|
else
|
115
|
-
File.join(::Rails.root.to_s, '
|
115
|
+
File.join(::Rails.root.to_s, 'public/docs' )
|
116
116
|
end
|
117
117
|
end
|
118
118
|
|
data/lib/rapidoc/resource_doc.rb
CHANGED
@@ -15,8 +15,8 @@ module Rapidoc
|
|
15
15
|
# @param routes_doc [RoutesDoc] routes documentation
|
16
16
|
#
|
17
17
|
def initialize( resource_name, routes_actions_info )
|
18
|
-
@name = resource_name.to_s
|
19
|
-
@controller_file =
|
18
|
+
@name = resource_name.to_s.split('/').last
|
19
|
+
@controller_file = resource_name.to_s.pluralize + '_controller' + controllers_extension
|
20
20
|
|
21
21
|
generate_info routes_actions_info
|
22
22
|
end
|
@@ -5,17 +5,17 @@
|
|
5
5
|
<title>Rapidoc - Action</title>
|
6
6
|
<meta name="description" content="Artículo en GenbetaDev sobre Bootstrap 2.0">
|
7
7
|
<meta name="author" content="Rafael Jurado González" >
|
8
|
-
<link href="
|
9
|
-
<link href="
|
10
|
-
<link href="
|
11
|
-
<script src="
|
12
|
-
<script src="
|
13
|
-
<script src="
|
8
|
+
<link href="../../assets/css/bootstrap.min.css" rel="stylesheet">
|
9
|
+
<link href="../../assets/css/rapidoc.css" rel="stylesheet">
|
10
|
+
<link href="../../assets/css/bootstrap-responsive.min.css" rel="stylesheet">
|
11
|
+
<script src="../../assets/js/jquery-1.9.0.min.js"></script>
|
12
|
+
<script src="../../assets/js/bootstrap.min.js"></script>
|
13
|
+
<script src="../../assets/js/json2.js"></script>
|
14
14
|
<style>
|
15
15
|
body { padding-top: 60px; }
|
16
16
|
</style>
|
17
17
|
</head>
|
18
|
-
<body
|
18
|
+
<body>
|
19
19
|
|
20
20
|
<div class="navbar navbar-fixed-top">
|
21
21
|
<div class="navbar-inner">
|
@@ -28,9 +28,11 @@
|
|
28
28
|
<a class="brand" href="#">{{info.project_name}}</a>
|
29
29
|
<div class="nav-collapse">
|
30
30
|
<ul class="nav">
|
31
|
-
<li><a href="
|
31
|
+
<li><a href="../../index.html">Resources</a></li>
|
32
32
|
<li class="active"><a href="#">Action</a></li>
|
33
|
-
|
33
|
+
{{#if info.contact}}
|
34
|
+
<li><a target="_blank" href="{{info.contact}}">Contact</a></li>
|
35
|
+
{{/if}}
|
34
36
|
</ul>
|
35
37
|
</div>
|
36
38
|
</div>
|
@@ -39,12 +41,13 @@
|
|
39
41
|
|
40
42
|
<div class="container">
|
41
43
|
<div class="page-header">
|
42
|
-
<h1><a href="
|
44
|
+
<h1><a href="../../index.html?collapse=collapse{{action.resource}}">{{action.resource}}</a></h1>
|
43
45
|
</div>
|
44
46
|
|
45
47
|
<ul class="nav nav-tabs" id="myTab">
|
46
48
|
<li class="active"><a href="#home">Home</a></li>
|
47
49
|
{{#if action.params}}<li><a href="#params">Params</a></li>{{/if}}
|
50
|
+
{{#if action.headers}}<li><a href="#headers">Headers</a></li>{{/if}}
|
48
51
|
{{#if action.errors}}<li><a href="#errors">Errors</a></li>{{/if}}
|
49
52
|
{{#if action.example_req}}<li><a href="#request">Request</a></li>{{/if}}
|
50
53
|
{{#if action.example_res}}<li><a href="#response">Response</a></li>{{/if}}
|
@@ -95,6 +98,7 @@
|
|
95
98
|
{{#if action.params}}
|
96
99
|
<div class="tab-pane my_tab" id="params">
|
97
100
|
<table class="table table-hover" id="table-params">
|
101
|
+
<tr><th>Name</th><th>Type</th><th>Description</th><th>Format</th></tr>
|
98
102
|
{{#each action.params}}
|
99
103
|
<tr>
|
100
104
|
<td>
|
@@ -113,9 +117,28 @@
|
|
113
117
|
{{/if}}
|
114
118
|
</td>
|
115
119
|
<td>{{this.description}}</td>
|
120
|
+
<td>{{this.format}}</td>
|
116
121
|
</tr>
|
117
122
|
{{/each}}
|
118
|
-
<tr><td></td><td><td></td></tr>
|
123
|
+
<tr><td></td><td><td></td><td></td></tr>
|
124
|
+
</table>
|
125
|
+
</div>
|
126
|
+
{{/if}}
|
127
|
+
|
128
|
+
{{#if action.headers}}
|
129
|
+
<div class="tab-pane my_tab" id="headers">
|
130
|
+
<table class="table table-hover" id="table-headers">
|
131
|
+
<tr><th>Name</th><th>Description</th></tr>
|
132
|
+
{{#each action.headers}}
|
133
|
+
<tr>
|
134
|
+
<td>
|
135
|
+
<strong>{{this.name}}</strong></br>
|
136
|
+
<span class="small">required</span>
|
137
|
+
</td>
|
138
|
+
<td>{{this.description}}</td>
|
139
|
+
</tr>
|
140
|
+
{{/each}}
|
141
|
+
<tr><td></td><td><td></tr>
|
119
142
|
</table>
|
120
143
|
</div>
|
121
144
|
{{/if}}
|
@@ -28,7 +28,9 @@
|
|
28
28
|
<div class="nav-collapse">
|
29
29
|
<ul class="nav">
|
30
30
|
<li class="active"><a href="index.html">Resources</a></li>
|
31
|
-
|
31
|
+
{{#if info.contact}}
|
32
|
+
<li><a target="_blank" href="{{info.contact}}">Contact</a></li>
|
33
|
+
{{/if}}
|
32
34
|
</ul>
|
33
35
|
</div>
|
34
36
|
</div>
|
@@ -64,7 +66,7 @@
|
|
64
66
|
</td>
|
65
67
|
<td>
|
66
68
|
{{#if ../this.has_controller_info}}
|
67
|
-
<a href="actions/{{../../this.
|
69
|
+
<a href="actions/{{../../this.resource_name}}/{{../../this.action}}.html">{{this}}<a>
|
68
70
|
{{else}}
|
69
71
|
{{this}}
|
70
72
|
{{/if}}
|
@@ -86,7 +88,6 @@
|
|
86
88
|
<script>
|
87
89
|
window.onload = function () {
|
88
90
|
var collapse = '#' + decodeURI( (RegExp(name + '=' + '(.+?)(&|$)').exec(location.search)||[,null])[1] );
|
89
|
-
console.log(collapse)
|
90
91
|
$(collapse).collapse('show')
|
91
92
|
}
|
92
93
|
</script>
|
@@ -8,7 +8,6 @@ module Rapidoc
|
|
8
8
|
def generate_index_template( resources_doc )
|
9
9
|
template = get_index_template
|
10
10
|
result = template.call( :info => rapidoc_config, :resources => resources_doc )
|
11
|
-
|
12
11
|
File.open( target_dir("index.html"), 'w' ) { |file| file.write result }
|
13
12
|
end
|
14
13
|
|
@@ -53,7 +52,14 @@ module Rapidoc
|
|
53
52
|
|
54
53
|
def create_action_template( template, action_doc )
|
55
54
|
result = template.call( :info => rapidoc_config, :action => action_doc )
|
56
|
-
|
55
|
+
resource = action_doc.resource.split('/').last
|
56
|
+
action = action_doc.action
|
57
|
+
dir_name = File.dirname(actions_dir("#{resource}"))
|
58
|
+
dir_name += "/#{resource}"
|
59
|
+
unless File.directory?(dir_name)
|
60
|
+
FileUtils.mkdir_p(dir_name)
|
61
|
+
end
|
62
|
+
File.open( actions_dir("#{resource}/#{action}.html"), 'w' ) { |file| file.write result }
|
57
63
|
end
|
58
64
|
|
59
65
|
def get_action_template
|
data/lib/rapidoc/version.rb
CHANGED
data/lib/rapidoc/yaml_parser.rb
CHANGED
@@ -14,15 +14,15 @@ module Rapidoc
|
|
14
14
|
#
|
15
15
|
def extract_resource_info( lines, blocks, file_name )
|
16
16
|
blocks ? info = [] : blocks = []
|
17
|
-
|
18
17
|
blocks.each.map do |b|
|
19
18
|
if lines[ b[:init] ].include? "=begin resource"
|
20
19
|
n_lines = b[:end] - b[:init] - 1
|
21
|
-
|
22
20
|
begin
|
23
21
|
info.push YAML.load( lines[ b[:init] +1, n_lines ].join.gsub(/\ *#/, '') )
|
24
|
-
rescue SyntaxError => e
|
22
|
+
rescue Psych::SyntaxError => e
|
25
23
|
puts "Error parsing block in #{file_name} file [#{b[:init]} - #{b[:end]}]"
|
24
|
+
rescue => e
|
25
|
+
puts e
|
26
26
|
end
|
27
27
|
end
|
28
28
|
end
|
@@ -44,7 +44,7 @@ module Rapidoc
|
|
44
44
|
blocks.each do |b|
|
45
45
|
if lines[ b[:init] ].include? "=begin action"
|
46
46
|
n_lines = b[:end] - b[:init] - 1
|
47
|
-
|
47
|
+
|
48
48
|
begin
|
49
49
|
info << YAML.load( lines[ b[:init] + 1, n_lines ].join.gsub(/\ *#/, '') )
|
50
50
|
rescue Exception => e
|
data/lib/tasks/rapidoc.rake
CHANGED
@@ -2,16 +2,25 @@ include Rapidoc
|
|
2
2
|
|
3
3
|
namespace :rapidoc do
|
4
4
|
|
5
|
+
desc "Generate config folder"
|
6
|
+
task :install do
|
7
|
+
create_config_structure
|
8
|
+
end
|
9
|
+
|
5
10
|
desc "Generate the api documentation"
|
6
11
|
task :generate do
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
+
if File.exists?( "#{::Rails.root}/config/rapidoc/rapidoc.yml" )
|
13
|
+
load_config
|
14
|
+
create_doc_structure
|
15
|
+
puts "Generating API documentation..."
|
16
|
+
generate_doc
|
17
|
+
puts "Completed API documentation generation"
|
18
|
+
else
|
19
|
+
puts "Need install rapidoc for run it, for install run rapidoc:install task"
|
20
|
+
end
|
12
21
|
end
|
13
22
|
|
14
|
-
desc "
|
23
|
+
desc "Remove the documentation"
|
15
24
|
task :clean do
|
16
25
|
remove_doc
|
17
26
|
end
|
data/rapidoc.gemspec
CHANGED
@@ -4,21 +4,22 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
|
|
4
4
|
require 'rapidoc/version'
|
5
5
|
|
6
6
|
Gem::Specification.new do |gem|
|
7
|
+
gem.license = "MIT"
|
7
8
|
gem.name = "rapidoc"
|
8
9
|
gem.version = Rapidoc::VERSION
|
9
|
-
gem.authors = ["Rafael Jurado"]
|
10
|
-
gem.email = ["rjurado@
|
10
|
+
gem.authors = ["Rafael Jurado, Harold Rangel, Luis Rodriguez"]
|
11
|
+
gem.email = ["rjurado@openmailbox.org, aarold.rangel@koombea.com, luis.rodriguez@koombea.com"]
|
11
12
|
gem.description = %q{Generates REST API documentation.}
|
12
13
|
gem.summary = %q{Generates REST API documentation.}
|
13
|
-
gem.homepage = "https://github.com/drinor/rapidoc
|
14
|
+
gem.homepage = "https://github.com/drinor/rapidoc"
|
14
15
|
|
15
16
|
gem.files = `git ls-files`.split($/)
|
16
17
|
gem.executables = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
|
17
18
|
gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
|
18
19
|
gem.require_paths = ["lib"]
|
19
20
|
|
20
|
-
gem.add_dependency "rails", ">= 3.2
|
21
|
-
gem.add_dependency "handlebars", "
|
21
|
+
gem.add_dependency "rails", ">= 3.2"
|
22
|
+
gem.add_dependency "handlebars", ">= 0.4.0"
|
22
23
|
gem.add_development_dependency "rspec-rails"
|
23
24
|
gem.add_development_dependency "sqlite3", "~> 1.3.7"
|
24
25
|
gem.add_development_dependency "capybara"
|