apitome 0.2.1 → 0.3.0
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.
- checksums.yaml +5 -5
- data/MIT.LICENSE +2 -2
- data/README.md +73 -49
- data/app/controllers/apitome/docs_controller.rb +57 -54
- data/app/helpers/apitome/docs_helper.rb +5 -9
- data/app/views/apitome/docs/_all_examples.html.erb +2 -2
- data/app/views/apitome/docs/_example.html.erb +3 -1
- data/app/views/apitome/docs/_params.html.erb +1 -1
- data/app/views/apitome/docs/show.html.erb +1 -1
- data/app/views/layouts/apitome/application.html.erb +4 -4
- data/lib/apitome/configuration.rb +24 -21
- data/lib/apitome/engine.rb +12 -12
- data/lib/apitome/version.rb +1 -1
- data/lib/generators/apitome/install/POST_INSTALL +1 -1
- data/lib/generators/apitome/install/install_generator.rb +7 -8
- data/lib/generators/apitome/install/templates/initializer.rb +21 -20
- metadata +10 -12
- data/config/routes.rb +0 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 03db784396e463e2e3117c3876221da9501bdf370b2b31d64af0aeb20832f6a7
|
|
4
|
+
data.tar.gz: 2c44ee118c18033c0ff752156b34501bc915afa2f1ff14db11bdd48cb63ad899
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2ad3ae73aac6bc4fda71089236cc5b1387ace99b0289777249da6cd0c5e44efb3e99d07d2107006a23149b902dc5890835b18fd9034c34759054436a1dd0731e
|
|
7
|
+
data.tar.gz: c565e5d1a99fc2157d7892bdd7bed7d8bf353c6472c234c8ac7468d0fc8eb50dc8511ee96a115b071343ddb61cf93bd71284644b2da72e5a26c872489f63ec83
|
data/MIT.LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Copyright
|
|
1
|
+
Copyright 2019 Jeremy Jackson / ModeSet
|
|
2
2
|
|
|
3
|
-
https://github.com/
|
|
3
|
+
https://github.com/jejacks0n/apitome
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining
|
|
6
6
|
a copy of this software and associated documentation files (the
|
data/README.md
CHANGED
|
@@ -2,24 +2,21 @@ Apitome
|
|
|
2
2
|
=======
|
|
3
3
|
|
|
4
4
|
[](https://rubygems.org/gems/apitome)
|
|
5
|
-
[](https://gemnasium.com/modeset/apitome)
|
|
6
5
|
[](https://travis-ci.org/jejacks0n/apitome)
|
|
7
|
-
[](https://codeclimate.com/github/jejacks0n/apitome/maintainability)
|
|
7
|
+
[](https://codeclimate.com/github/jejacks0n/apitome/test_coverage)
|
|
9
8
|
[](http://opensource.org/licenses/MIT)
|
|
10
9
|
|
|
11
|
-
Apitome is a API documentation tool for Rails built on top of the great
|
|
10
|
+
Apitome is a API documentation tool for Rails built on top of the great RSpec DSL included in
|
|
12
11
|
[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation) (RAD). It's designed to display the
|
|
13
|
-
documentation generated by RAD in either a single page
|
|
14
|
-
|
|
12
|
+
documentation generated by RAD in either a single page, or on individual pages, and uses Bootstrap for most of the basic
|
|
13
|
+
styling and [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting.
|
|
15
14
|
|
|
16
15
|
You can provide a markdown file that will be displayed as the README page, and by taking advantage of its modular view
|
|
17
16
|
structure you can override any number of views and partials to customize the output. You can also specify custom css and
|
|
18
17
|
javascript if you want to do fancier things or change how it looks.
|
|
19
18
|
|
|
20
|
-
|
|
21
19
|
## Installation
|
|
22
|
-
|
|
23
20
|
Add it to your Gemfile.
|
|
24
21
|
|
|
25
22
|
```ruby
|
|
@@ -32,6 +29,8 @@ Optionally run the install generator to get the initializer and an initial readm
|
|
|
32
29
|
rails generate apitome:install
|
|
33
30
|
```
|
|
34
31
|
|
|
32
|
+
You can get the assets installed using the generator by providing a `--assets` flag.
|
|
33
|
+
|
|
35
34
|
Update your `spec_helper.rb` to adjust how RAD outputs its results -- Apitome reads these JSON files to generate the
|
|
36
35
|
documentation.
|
|
37
36
|
|
|
@@ -41,117 +40,142 @@ RspecApiDocumentation.configure do |config|
|
|
|
41
40
|
end
|
|
42
41
|
```
|
|
43
42
|
|
|
44
|
-
|
|
45
43
|
## Usage
|
|
46
|
-
|
|
47
44
|
You can view your documentation at the default `api/docs` route.
|
|
48
45
|
|
|
49
|
-
|
|
50
46
|
## Configuration
|
|
51
|
-
|
|
52
|
-
|
|
47
|
+
After installation, your app will have an apitome initializer (app/config/initializers/apitome.rb). You will find the
|
|
48
|
+
following parameters that can be used to customize apitome. Note: Restart rails after changing any of these parameters.
|
|
53
49
|
|
|
54
50
|
<dl>
|
|
55
|
-
|
|
56
51
|
<dt> mount_at </dt><dd>
|
|
57
|
-
This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would
|
|
58
|
-
|
|
52
|
+
This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would
|
|
53
|
+
allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount
|
|
54
|
+
it yourself if you need to.
|
|
55
|
+
<br/>
|
|
59
56
|
<b>default:</b> <code>"/api/docs"</code>
|
|
60
57
|
</dd>
|
|
61
58
|
|
|
62
59
|
<dt> root </dt><dd>
|
|
63
|
-
This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application
|
|
64
|
-
|
|
60
|
+
This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application
|
|
61
|
+
it can be useful to set this to your engines root. (E.g. <code>Application::Engine.root</code>)
|
|
62
|
+
<br/>
|
|
65
63
|
<b>default:</b> <code>nil</code>
|
|
66
64
|
</dd>
|
|
67
65
|
|
|
68
66
|
<dt> doc_path </dt><dd>
|
|
69
|
-
This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is
|
|
70
|
-
|
|
67
|
+
This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is
|
|
68
|
+
configurable here.
|
|
69
|
+
<br/>
|
|
71
70
|
<b>default:</b> <code>"doc/api"</code>
|
|
72
71
|
</dd>
|
|
73
72
|
|
|
74
73
|
<dt> parent_controller </dt><dd>
|
|
75
|
-
Set
|
|
76
|
-
|
|
74
|
+
Set the parent controller that Apitome::DocsController will inherit from. Useful if you want to use a custom
|
|
75
|
+
<code>before_action</code> for instance.
|
|
76
|
+
<br/>
|
|
77
77
|
<b>default:</b> <code>"ActionController::Base"</code>
|
|
78
78
|
</dd>
|
|
79
79
|
|
|
80
80
|
<dt> title </dt><dd>
|
|
81
|
-
The title of the documentation -- If your project has a name, you'll want to put it here
|
|
82
|
-
|
|
81
|
+
The title of the documentation -- If your project has a name, you'll want to put it here.
|
|
82
|
+
<br/>
|
|
83
83
|
<b>default:</b> <code>"Apitome Documentation"</code>
|
|
84
84
|
</dd>
|
|
85
85
|
|
|
86
86
|
<dt> layout </dt><dd>
|
|
87
|
-
The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own
|
|
88
|
-
|
|
87
|
+
The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own
|
|
88
|
+
application layout.
|
|
89
|
+
<br/>
|
|
89
90
|
<b>default:</b> <code>"apitome/application"</code>
|
|
90
91
|
</dd>
|
|
91
92
|
|
|
92
93
|
<dt> code_theme </dt><dd>
|
|
93
|
-
We're using [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some
|
|
94
|
-
|
|
94
|
+
We're using [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some
|
|
95
|
+
great themes. You can check [here for themes](http://softwaremaniacs.org/media/soft/highlight/test.html), and enter
|
|
96
|
+
the theme as lowercase/underscore.
|
|
97
|
+
<br/>
|
|
95
98
|
<b>default:</b> <code>"default"</code>
|
|
96
99
|
</dd>
|
|
97
100
|
|
|
98
101
|
<dt> css_override </dt><dd>
|
|
99
|
-
This allows you to override the css manually. You typically want to require
|
|
100
|
-
|
|
102
|
+
This allows you to override the css manually. You typically want to require <code>apitome/application</code> within the
|
|
103
|
+
override, but if you want to override it entirely you can do so.
|
|
104
|
+
<br/>
|
|
101
105
|
<b>default:</b> <code>nil</code>
|
|
102
106
|
</dd>
|
|
103
107
|
|
|
104
108
|
<dt> js_override </dt><dd>
|
|
105
|
-
This allows you to override the javascript manually. You typically want to require
|
|
106
|
-
|
|
109
|
+
This allows you to override the javascript manually. You typically want to require <code>apitome/application</code> within the
|
|
110
|
+
override, but if you want to override it entirely you can do so.
|
|
111
|
+
<br/>
|
|
107
112
|
<b>default:</b> <code>nil</code>
|
|
108
113
|
</dd>
|
|
109
114
|
|
|
110
115
|
<dt> readme </dt><dd>
|
|
111
|
-
You can provide a "README" style markdown file for the documentation, which is a useful place to include general
|
|
112
|
-
|
|
116
|
+
You can provide a "README" style markdown file for the documentation, which is a useful place to include general
|
|
117
|
+
information. This path is relative to your doc_path configuration.
|
|
118
|
+
<br/>
|
|
113
119
|
<b>default:</b> <code>"../api.md"</code>
|
|
114
120
|
</dd>
|
|
115
121
|
|
|
116
122
|
<dt> single_page </dt><dd>
|
|
117
|
-
Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on
|
|
118
|
-
|
|
123
|
+
Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on
|
|
124
|
+
individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.
|
|
125
|
+
<br/>
|
|
119
126
|
<b>default:</b> <code>true</code>
|
|
127
|
+
</dd>
|
|
120
128
|
|
|
121
129
|
<dt> url_formatter </dt><dd>
|
|
122
|
-
You can specify how urls are formatted using a Proc or other callable object. Your proc will be called with a
|
|
123
|
-
|
|
130
|
+
You can specify how urls are formatted using a Proc or other callable object. Your proc will be called with a
|
|
131
|
+
resource name or link, giving you the opportunity to modify it as necessary for in the documentation url.
|
|
132
|
+
<br/>
|
|
124
133
|
<b>default:</b> <code>-> (str) { str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-') }</code>
|
|
125
134
|
</dd>
|
|
126
135
|
|
|
136
|
+
<dt> remote_url </dt><dd>
|
|
137
|
+
You can setup the docs to be loaded from a remote URL if they are not available in the application environment. This
|
|
138
|
+
URL is used as the base location and should be set to where the readme is located. If left nil, local is assumed.
|
|
139
|
+
<br/>
|
|
140
|
+
<b>default:</b> <code>nil</code>
|
|
141
|
+
</dd>
|
|
142
|
+
|
|
143
|
+
<dt> http_basic_authentication </dt><dd>
|
|
144
|
+
If using remote urls you can fetch the remote docs using HTTP Basic Authentication by configuring this to be an
|
|
145
|
+
array of the user and password. (E.g. <code>['user', 'password']</code>)
|
|
146
|
+
<br/>
|
|
147
|
+
<b>default:</b> <code>nil</code>
|
|
148
|
+
</dd>
|
|
149
|
+
|
|
127
150
|
<dt> precompile_assets </dt><dd>
|
|
128
|
-
By default all assets that ship with this library are precompiled by the asset pipeline. If you would prefer to
|
|
151
|
+
By default all assets that ship with this library are precompiled by the asset pipeline. If you would prefer to
|
|
152
|
+
control this yourself, you can disable it by changing this to false.
|
|
153
|
+
<br/>
|
|
154
|
+
<b>default:</b> <code>true</code>
|
|
155
|
+
</dd>
|
|
129
156
|
|
|
157
|
+
<dt> simulated_response </dt><dd>
|
|
158
|
+
If <code>simulated_response</code> is disabled you can hide the "Simulated Response" links.
|
|
159
|
+
<br>
|
|
130
160
|
<b>default:</b> <code>true</code>
|
|
131
161
|
</dd>
|
|
132
|
-
=======
|
|
133
162
|
|
|
134
163
|
When you install Apitime an initializer file (app/config/initializers/apitome.rb) is generated that contains good
|
|
135
164
|
documentation for each configuration directive. Otherwise you can get a refresher by checking the
|
|
136
165
|
[Apitome Configuration](https://github.com/modeset/apitome/wiki/Apitome-Configuration) article.
|
|
137
166
|
|
|
138
167
|
## Customization
|
|
139
|
-
|
|
140
|
-
You can put
|
|
141
|
-
|
|
142
|
-
path and they will be overridden.
|
|
168
|
+
You can put custom views and partials in your own `views/apitome/docs` -- check
|
|
169
|
+
[here for examples](tree/master/app/views/apitome/docs). You can put any partial in your own path and they will be
|
|
170
|
+
overridden.
|
|
143
171
|
|
|
144
172
|
Additional customization can come in the form of providing custom css and javascript. You can do this by creating the
|
|
145
173
|
files you want (that often times require the default assets in the gem), and then configure Apitome to use those instead
|
|
146
174
|
of the defaults.
|
|
147
175
|
|
|
148
|
-
|
|
149
176
|
## License
|
|
150
|
-
|
|
151
177
|
Licensed under the [MIT License](http://creativecommons.org/licenses/MIT/)
|
|
152
178
|
|
|
153
|
-
Copyright
|
|
154
|
-
|
|
179
|
+
Copyright 2016 [jejacks0n](https://github.com/jejacks0n)
|
|
155
180
|
|
|
156
181
|
## Make Code Not War
|
|
157
|
-
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
require
|
|
1
|
+
require "open-uri"
|
|
2
2
|
|
|
3
3
|
class Apitome::DocsController < Object.const_get(Apitome.configuration.parent_controller)
|
|
4
4
|
layout Apitome.configuration.layout
|
|
@@ -24,7 +24,7 @@ class Apitome::DocsController < Object.const_get(Apitome.configuration.parent_co
|
|
|
24
24
|
def simulate
|
|
25
25
|
request = example["requests"][0]
|
|
26
26
|
if request
|
|
27
|
-
request["response_headers"].delete(
|
|
27
|
+
request["response_headers"].delete("Content-Length")
|
|
28
28
|
request["response_headers"].each { |k, v| headers[k] = v }
|
|
29
29
|
render body: request["response_body"], status: request["response_status"]
|
|
30
30
|
else
|
|
@@ -34,72 +34,75 @@ class Apitome::DocsController < Object.const_get(Apitome.configuration.parent_co
|
|
|
34
34
|
|
|
35
35
|
private
|
|
36
36
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
"#{file}"
|
|
37
|
+
def file_for(file, readme: false)
|
|
38
|
+
if Apitome.configuration.remote_url
|
|
39
|
+
file = readme ? file : "#{Apitome.configuration.doc_path}/#{file}"
|
|
40
|
+
file = CGI.escape("#{Apitome.configuration.remote_url}/#{file}")
|
|
41
41
|
else
|
|
42
|
-
|
|
42
|
+
file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
|
|
43
|
+
raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exist?(file)
|
|
43
44
|
end
|
|
44
45
|
|
|
45
|
-
file
|
|
46
|
-
else
|
|
47
|
-
file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
|
|
48
|
-
raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exists?(file)
|
|
46
|
+
open(file, file_opts).read
|
|
49
47
|
end
|
|
50
48
|
|
|
51
|
-
|
|
52
|
-
|
|
49
|
+
def resources
|
|
50
|
+
@resources ||= JSON.parse(file_for("index.json"))["resources"]
|
|
51
|
+
end
|
|
53
52
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
53
|
+
def example
|
|
54
|
+
@example ||= JSON.parse(file_for("#{params[:path]}.json"))
|
|
55
|
+
end
|
|
57
56
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
57
|
+
def set_example(resource)
|
|
58
|
+
@example = JSON.parse(file_for("#{resource}.json"))
|
|
59
|
+
end
|
|
61
60
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
61
|
+
def file_opts
|
|
62
|
+
if Apitome.configuration.remote_url && Apitome.configuration.http_basic_authentication
|
|
63
|
+
{ http_basic_authentication: Apitome.configuration.http_basic_authentication }
|
|
64
|
+
else
|
|
65
|
+
{}
|
|
66
|
+
end
|
|
67
|
+
end
|
|
65
68
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
69
|
+
def formatted_readme
|
|
70
|
+
return unless Apitome.configuration.readme
|
|
71
|
+
rendered_markdown(file_for(Apitome.configuration.readme, readme: true))
|
|
72
|
+
end
|
|
70
73
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
74
|
+
def rendered_markdown(string)
|
|
75
|
+
if defined?(GitHub::Markdown)
|
|
76
|
+
GitHub::Markdown.render(string)
|
|
77
|
+
else
|
|
78
|
+
Kramdown::Document.new(string).to_html
|
|
79
|
+
end
|
|
76
80
|
end
|
|
77
|
-
end
|
|
78
81
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
82
|
+
def formatted_body(body, type)
|
|
83
|
+
if type =~ /json/ && body.present?
|
|
84
|
+
JSON.pretty_generate(JSON.parse(body))
|
|
85
|
+
else
|
|
86
|
+
body
|
|
87
|
+
end
|
|
88
|
+
rescue JSON::ParserError
|
|
89
|
+
return body if body == " "
|
|
90
|
+
raise JSON::ParserError
|
|
84
91
|
end
|
|
85
|
-
rescue JSON::ParserError
|
|
86
|
-
return body if body == " "
|
|
87
|
-
raise JSON::ParserError
|
|
88
|
-
end
|
|
89
92
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
93
|
+
def param_headers(params)
|
|
94
|
+
titles = %w{Name Description}
|
|
95
|
+
titles += param_extras(params)
|
|
96
|
+
titles
|
|
97
|
+
end
|
|
95
98
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
99
|
+
def param_extras(params)
|
|
100
|
+
params.map do |param|
|
|
101
|
+
param.reject { |k, _v| %w{name description required scope}.include?(k) }.keys
|
|
102
|
+
end.flatten.uniq
|
|
103
|
+
end
|
|
101
104
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
+
def id_for(str)
|
|
106
|
+
Apitome.configuration.url_formatter.call(str)
|
|
107
|
+
end
|
|
105
108
|
end
|
|
@@ -1,20 +1,16 @@
|
|
|
1
1
|
module Apitome::DocsHelper
|
|
2
|
-
def format_scope(
|
|
3
|
-
Array(
|
|
4
|
-
|
|
5
|
-
scope
|
|
6
|
-
else
|
|
7
|
-
"[#{scope}]"
|
|
8
|
-
end
|
|
2
|
+
def format_scope(scopes)
|
|
3
|
+
Array(scopes).each_with_index.map do |scope, index|
|
|
4
|
+
index == 0 ? scope : "[#{scope}]"
|
|
9
5
|
end.join
|
|
10
6
|
end
|
|
11
7
|
|
|
12
8
|
def resource_link(resource)
|
|
13
|
-
"#{Apitome.configuration.mount_at}/#{resource['examples'].first['link'].gsub(/\.json$/, '')}"
|
|
9
|
+
"#{Apitome.configuration.mount_at}/#{CGI.escape(resource['examples'].first['link'].gsub(/\.json$/, ''))}"
|
|
14
10
|
end
|
|
15
11
|
|
|
16
12
|
def example_link(example)
|
|
17
|
-
"#{Apitome.configuration.mount_at}/#{example['link'].gsub(/\.json$/, '')}"
|
|
13
|
+
"#{Apitome.configuration.mount_at}/#{CGI.escape(example['link'].gsub(/\.json$/, ''))}"
|
|
18
14
|
end
|
|
19
15
|
|
|
20
16
|
def link_active?(link)
|
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
<%= render partial: 'resource_explanation', locals: { explanation: resource['explanation'] } if resource['explanation'] %>
|
|
6
6
|
|
|
7
7
|
<% resource['examples'].each do |example| %>
|
|
8
|
-
<% link = example['link'].gsub(
|
|
8
|
+
<% link = example['link'].gsub(/.json$/, '') %>
|
|
9
9
|
<article id="<%= id_for(link) %>">
|
|
10
|
-
<%= render partial: 'example', locals: { example: set_example(link)
|
|
10
|
+
<%= render partial: 'example', locals: { example: set_example(link).merge!(link: link) } %>
|
|
11
11
|
</article>
|
|
12
12
|
<% end %>
|
|
13
13
|
</section>
|
|
@@ -17,7 +17,9 @@
|
|
|
17
17
|
|
|
18
18
|
<h3><%= t(:response, scope: :apitome) %></h3>
|
|
19
19
|
<div class="response">
|
|
20
|
-
|
|
20
|
+
<%- if Apitome.configuration.simulated_response %>
|
|
21
|
+
<%= link_to('Simulated Response', simulated_path(example[:link])) if example[:link].present? %>
|
|
22
|
+
<%- end %>
|
|
21
23
|
<%= render partial: 'apitome/docs/response_fields', locals: {params: example['response_fields']} if example['response_fields'].size > 0 %>
|
|
22
24
|
<%= render partial: 'apitome/docs/status', locals: {request: request, index: index} %>
|
|
23
25
|
<%= render partial: 'apitome/docs/headers', locals: {request: request, index: index, headers: request['response_headers']} %>
|
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
<h1 class="resource-name"><%= example['resource'] %></h1>
|
|
2
2
|
<%= render partial: 'resource_explanation', locals: { explanation: example['resource_explanation'] } if example['resource_explanation'] %>
|
|
3
|
-
<%= render partial: 'example', locals: { example: example
|
|
3
|
+
<%= render partial: 'example', locals: { example: example.merge!(link: params[:path]) } %>
|
|
@@ -3,11 +3,11 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<title><%= Apitome.configuration.title %></title>
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
-
<%= stylesheet_link_tag
|
|
7
|
-
<%= stylesheet_link_tag
|
|
8
|
-
<%= javascript_include_tag Apitome.configuration.js_override ||
|
|
6
|
+
<%= stylesheet_link_tag Apitome.configuration.css_override || "apitome/application", media: "all" %>
|
|
7
|
+
<%= stylesheet_link_tag "apitome/highlight_themes/#{Apitome.configuration.code_theme}", media: "all" %>
|
|
8
|
+
<%= javascript_include_tag Apitome.configuration.js_override || "apitome/application" %>
|
|
9
9
|
</head>
|
|
10
|
-
<body class="<%= Apitome.configuration.single_page ?
|
|
10
|
+
<body class="<%= Apitome.configuration.single_page ? "single-page" : "" %>">
|
|
11
11
|
|
|
12
12
|
<div class="container">
|
|
13
13
|
<%= render 'header' %>
|
|
@@ -1,5 +1,9 @@
|
|
|
1
|
+
require "singleton"
|
|
2
|
+
|
|
1
3
|
module Apitome
|
|
2
4
|
class Configuration
|
|
5
|
+
include Singleton
|
|
6
|
+
|
|
3
7
|
cattr_accessor *[
|
|
4
8
|
:mount_at,
|
|
5
9
|
:root,
|
|
@@ -12,41 +16,40 @@ module Apitome
|
|
|
12
16
|
:js_override,
|
|
13
17
|
:readme,
|
|
14
18
|
:single_page,
|
|
15
|
-
:remote_docs,
|
|
16
|
-
:remote_url,
|
|
17
19
|
:url_formatter,
|
|
18
|
-
:
|
|
20
|
+
:remote_url,
|
|
21
|
+
:http_basic_authentication,
|
|
22
|
+
:precompile_assets,
|
|
23
|
+
:simulated_response,
|
|
19
24
|
]
|
|
20
25
|
|
|
21
|
-
@@mount_at
|
|
22
|
-
@@root
|
|
23
|
-
@@doc_path
|
|
26
|
+
@@mount_at = "/api/docs"
|
|
27
|
+
@@root = nil # will default to Rails.root if left unset
|
|
28
|
+
@@doc_path = "doc/api"
|
|
24
29
|
@@parent_controller = "ActionController::Base"
|
|
25
|
-
@@title
|
|
26
|
-
@@layout
|
|
27
|
-
@@code_theme
|
|
28
|
-
@@css_override
|
|
29
|
-
@@js_override
|
|
30
|
-
@@readme
|
|
31
|
-
@@single_page
|
|
32
|
-
@@
|
|
33
|
-
@@remote_url
|
|
34
|
-
@@
|
|
30
|
+
@@title = "Apitome Documentation"
|
|
31
|
+
@@layout = "apitome/application"
|
|
32
|
+
@@code_theme = "default"
|
|
33
|
+
@@css_override = nil
|
|
34
|
+
@@js_override = nil
|
|
35
|
+
@@readme = "../api.md"
|
|
36
|
+
@@single_page = true
|
|
37
|
+
@@url_formatter = -> (str) { str.gsub(/\.json$/, "").underscore.gsub(/[^0-9a-z]+/i, "-") }
|
|
38
|
+
@@remote_url = nil
|
|
39
|
+
@@http_basic_authentication = nil
|
|
35
40
|
@@precompile_assets = true
|
|
41
|
+
@@simulated_response = true
|
|
36
42
|
|
|
37
43
|
def self.root=(path)
|
|
38
44
|
@@root = Pathname.new(path.to_s) if path.present?
|
|
39
45
|
end
|
|
40
|
-
|
|
41
|
-
def self.code_theme_url
|
|
42
|
-
"apitome/highlight_themes/#{@@code_theme}"
|
|
43
|
-
end
|
|
44
46
|
end
|
|
45
47
|
|
|
46
48
|
mattr_accessor :configuration
|
|
47
49
|
@@configuration = Configuration
|
|
48
50
|
|
|
49
|
-
def self.
|
|
51
|
+
def self.configure
|
|
50
52
|
yield @@configuration
|
|
51
53
|
end
|
|
54
|
+
singleton_class.send(:alias_method, :setup, :configure)
|
|
52
55
|
end
|
data/lib/apitome/engine.rb
CHANGED
|
@@ -1,26 +1,26 @@
|
|
|
1
1
|
module Apitome
|
|
2
2
|
class Engine < ::Rails::Engine
|
|
3
3
|
isolate_namespace Apitome
|
|
4
|
+
apitome = Apitome.configuration
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
routes do
|
|
7
|
+
root to: "docs#index"
|
|
8
|
+
get "/simulate/*path", to: "docs#simulate", as: :simulated if apitome.simulated_response
|
|
9
|
+
get "/*path", to: "docs#show" unless Apitome.configuration.single_page
|
|
9
10
|
end
|
|
10
11
|
|
|
11
|
-
config.assets.paths << root.join('assets', 'stylesheets').to_s
|
|
12
|
-
config.assets.paths << root.join('assets', 'javascripts').to_s
|
|
13
|
-
|
|
14
12
|
initializer :assets, group: :all do |app|
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
apitome.root ||= app.root
|
|
14
|
+
|
|
15
|
+
config.assets.precompile += ["apitome/*.css", "apitome/*.js"]
|
|
16
|
+
config.assets.paths << root.join("assets", "stylesheets").to_s
|
|
17
|
+
config.assets.paths << root.join("assets", "javascripts").to_s
|
|
17
18
|
end
|
|
18
19
|
|
|
19
20
|
config.after_initialize do |app|
|
|
20
|
-
|
|
21
|
-
if Apitome.configuration.mount_at.present?
|
|
21
|
+
if apitome.mount_at.present?
|
|
22
22
|
app.routes.prepend do
|
|
23
|
-
mount Apitome::Engine =>
|
|
23
|
+
mount Apitome::Engine => apitome.mount_at
|
|
24
24
|
end
|
|
25
25
|
end
|
|
26
26
|
end
|
data/lib/apitome/version.rb
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
+============================================================================+
|
|
2
2
|
Congratulations! Apitome was successfully installed.
|
|
3
3
|
|
|
4
|
-
Documentation and more can be found at: https://github.com/
|
|
4
|
+
Documentation and more can be found at: https://github.com/jejacks0n/apitome
|
|
@@ -5,11 +5,8 @@ module Apitome
|
|
|
5
5
|
|
|
6
6
|
desc "Installs the Apitome initializer and markdown file into your application."
|
|
7
7
|
|
|
8
|
-
class_option :assets,
|
|
9
|
-
|
|
10
|
-
aliases: "-a",
|
|
11
|
-
default: false,
|
|
12
|
-
desc: "Install the javascript and stylesheet assets to /public"
|
|
8
|
+
class_option :assets, type: :boolean, default: false,
|
|
9
|
+
aliases: "-a", desc: "Install the javascript and stylesheet assets to /public"
|
|
13
10
|
|
|
14
11
|
def copy_initializers
|
|
15
12
|
copy_file "templates/initializer.rb", "config/initializers/apitome.rb"
|
|
@@ -18,11 +15,13 @@ module Apitome
|
|
|
18
15
|
|
|
19
16
|
def copy_assets
|
|
20
17
|
return unless options[:assets]
|
|
21
|
-
|
|
22
|
-
|
|
18
|
+
@asset_root = "../../../../app/assets"
|
|
19
|
+
|
|
20
|
+
copy_file "#{@asset_root}/javascripts/apitome/bundle.js", "public/javascripts/apitome/application.js"
|
|
21
|
+
copy_file "#{@asset_root}/stylesheets/apitome/bundle.css", "public/stylesheets/apitome/application.css"
|
|
23
22
|
end
|
|
24
23
|
|
|
25
|
-
def
|
|
24
|
+
def display_post_install
|
|
26
25
|
readme "POST_INSTALL" if behavior == :invoke
|
|
27
26
|
end
|
|
28
27
|
end
|
|
@@ -1,19 +1,19 @@
|
|
|
1
|
-
Apitome.
|
|
2
|
-
# This determines where the Apitome routes will be mounted. Changing this to
|
|
1
|
+
Apitome.configure do |config|
|
|
2
|
+
# This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would
|
|
3
3
|
# allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount
|
|
4
4
|
# it yourself if you need to.
|
|
5
5
|
config.mount_at = "/api/docs"
|
|
6
6
|
|
|
7
7
|
# This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application
|
|
8
|
-
# it can be useful to set this to your engines root.. E.g. Application::Engine.root
|
|
8
|
+
# it can be useful to set this to your engines root.. E.g. `Application::Engine.root`
|
|
9
9
|
config.root = nil
|
|
10
10
|
|
|
11
11
|
# This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is
|
|
12
12
|
# configurable here.
|
|
13
13
|
config.doc_path = "doc/api"
|
|
14
14
|
|
|
15
|
-
# Set
|
|
16
|
-
# `before_action
|
|
15
|
+
# Set the parent controller that Apitome::DocsController will inherit from. Useful if you want to use a custom
|
|
16
|
+
# `before_action` for instance.
|
|
17
17
|
config.parent_controller = "ActionController::Base"
|
|
18
18
|
|
|
19
19
|
# The title of the documentation -- If your project has a name, you'll want to put it here.
|
|
@@ -24,8 +24,8 @@ Apitome.setup do |config|
|
|
|
24
24
|
config.layout = "apitome/application"
|
|
25
25
|
|
|
26
26
|
# We're using highlight.js (https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some
|
|
27
|
-
# great themes. You can check http://softwaremaniacs.org/media/soft/highlight/test.html
|
|
28
|
-
# theme as lowercase/underscore.
|
|
27
|
+
# great themes. You can check [here for themes](http://softwaremaniacs.org/media/soft/highlight/test.html), and enter
|
|
28
|
+
# the theme as lowercase/underscore.
|
|
29
29
|
config.code_theme = "default"
|
|
30
30
|
|
|
31
31
|
# This allows you to override the css manually. You typically want to require `apitome/application` within the
|
|
@@ -36,7 +36,7 @@ Apitome.setup do |config|
|
|
|
36
36
|
# override, but if you want to override it entirely you can do so.
|
|
37
37
|
config.js_override = nil
|
|
38
38
|
|
|
39
|
-
# You can provide a
|
|
39
|
+
# You can provide a "README" style markdown file for the documentation, which is a useful place to include general
|
|
40
40
|
# information. This path is relative to your doc_path configuration.
|
|
41
41
|
config.readme = "../api.md"
|
|
42
42
|
|
|
@@ -44,22 +44,23 @@ Apitome.setup do |config|
|
|
|
44
44
|
# individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.
|
|
45
45
|
config.single_page = true
|
|
46
46
|
|
|
47
|
-
# You can specify how urls are formatted using a Proc or other callable object.
|
|
48
|
-
#
|
|
47
|
+
# You can specify how urls are formatted using a Proc or other callable object. Your proc will be called with a
|
|
48
|
+
# resource name or link, giving you the opportunity to modify it as necessary for in the documentation url.
|
|
49
49
|
config.url_formatter = -> (str) { str.gsub(/\.json$/, '').underscore.gsub(/[^0-9a-z\:]+/i, '-') }
|
|
50
50
|
|
|
51
|
-
# You can setup the docs to be loaded from a remote URL if they are
|
|
52
|
-
#
|
|
53
|
-
# false.
|
|
54
|
-
config.remote_docs = false
|
|
55
|
-
|
|
56
|
-
# If the remote_docs is set to true, this URL is used as the base for
|
|
57
|
-
# the doc location. This should be the root of the doc location, where
|
|
58
|
-
# the readme is located. It uses the doc_path setting to build the
|
|
59
|
-
# URLs for the API documentation. This defaults to nil.
|
|
51
|
+
# You can setup the docs to be loaded from a remote URL if they are not available in the application environment. This
|
|
52
|
+
# URL is used as the base location and should be set to where the readme is located. If left nil, local is assumed.
|
|
60
53
|
config.remote_url = nil
|
|
61
54
|
|
|
55
|
+
# If the remote_docs is set to true, and the remote URL is protected by
|
|
56
|
+
# HTTP Basic Authentication you can set the user and password here as an array.
|
|
57
|
+
# Usage: `http_basic_authentication = ['user', 'password']`.
|
|
58
|
+
# This defaults to nil.
|
|
59
|
+
config.http_basic_authentication = nil
|
|
60
|
+
|
|
62
61
|
# If you would like to precompile your own assets, you can disable auto-compilation.
|
|
63
|
-
# This defaults to true
|
|
64
62
|
config.precompile_assets = true
|
|
63
|
+
|
|
64
|
+
# If you do not want "Simulated Response" links to appear you can disable them.
|
|
65
|
+
config.simulated_response = true
|
|
65
66
|
end
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: apitome
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.3.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- jejacks0n
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2019-
|
|
11
|
+
date: 2019-04-13 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: railties
|
|
@@ -25,13 +25,13 @@ dependencies:
|
|
|
25
25
|
- !ruby/object:Gem::Version
|
|
26
26
|
version: '0'
|
|
27
27
|
- !ruby/object:Gem::Dependency
|
|
28
|
-
name:
|
|
28
|
+
name: kramdown
|
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|
|
30
30
|
requirements:
|
|
31
31
|
- - ">="
|
|
32
32
|
- !ruby/object:Gem::Version
|
|
33
33
|
version: '0'
|
|
34
|
-
type: :
|
|
34
|
+
type: :runtime
|
|
35
35
|
prerelease: false
|
|
36
36
|
version_requirements: !ruby/object:Gem::Requirement
|
|
37
37
|
requirements:
|
|
@@ -39,13 +39,13 @@ dependencies:
|
|
|
39
39
|
- !ruby/object:Gem::Version
|
|
40
40
|
version: '0'
|
|
41
41
|
- !ruby/object:Gem::Dependency
|
|
42
|
-
name:
|
|
42
|
+
name: rspec_api_documentation
|
|
43
43
|
requirement: !ruby/object:Gem::Requirement
|
|
44
44
|
requirements:
|
|
45
45
|
- - ">="
|
|
46
46
|
- !ruby/object:Gem::Version
|
|
47
47
|
version: '0'
|
|
48
|
-
type: :
|
|
48
|
+
type: :development
|
|
49
49
|
prerelease: false
|
|
50
50
|
version_requirements: !ruby/object:Gem::Requirement
|
|
51
51
|
requirements:
|
|
@@ -55,7 +55,7 @@ dependencies:
|
|
|
55
55
|
description: API documentation renderer for Rails using RSpec API Documentation JSON
|
|
56
56
|
output
|
|
57
57
|
email:
|
|
58
|
-
-
|
|
58
|
+
- jejacks0n@gmail.com
|
|
59
59
|
executables: []
|
|
60
60
|
extensions: []
|
|
61
61
|
extra_rdoc_files: []
|
|
@@ -88,7 +88,6 @@ files:
|
|
|
88
88
|
- app/views/layouts/apitome/application.html.erb
|
|
89
89
|
- config/locales/en.yml
|
|
90
90
|
- config/locales/es.yml
|
|
91
|
-
- config/routes.rb
|
|
92
91
|
- lib/apitome.rb
|
|
93
92
|
- lib/apitome/configuration.rb
|
|
94
93
|
- lib/apitome/engine.rb
|
|
@@ -180,7 +179,7 @@ files:
|
|
|
180
179
|
- vendor/assets/stylesheets/apitome/highlight_themes/xcode.css
|
|
181
180
|
- vendor/assets/stylesheets/apitome/highlight_themes/xt256.css
|
|
182
181
|
- vendor/assets/stylesheets/apitome/highlight_themes/zenburn.css
|
|
183
|
-
homepage: https://github.com/
|
|
182
|
+
homepage: https://github.com/jejacks0n/apitome
|
|
184
183
|
licenses:
|
|
185
184
|
- MIT
|
|
186
185
|
metadata: {}
|
|
@@ -192,15 +191,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
192
191
|
requirements:
|
|
193
192
|
- - "~>"
|
|
194
193
|
- !ruby/object:Gem::Version
|
|
195
|
-
version: '2.
|
|
194
|
+
version: '2.4'
|
|
196
195
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
197
196
|
requirements:
|
|
198
197
|
- - ">="
|
|
199
198
|
- !ruby/object:Gem::Version
|
|
200
199
|
version: '0'
|
|
201
200
|
requirements: []
|
|
202
|
-
|
|
203
|
-
rubygems_version: 2.6.12
|
|
201
|
+
rubygems_version: 3.0.3
|
|
204
202
|
signing_key:
|
|
205
203
|
specification_version: 4
|
|
206
204
|
summary: 'Apitome: /iˈpitəmē/ An API documentation reader RSpec API Documentation'
|