dox 1.0.0.alpha → 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.gitignore +2 -0
- data/.rubocop.yml +14 -0
- data/.ruby-version +1 -0
- data/.travis.yml +23 -2
- data/CHANGES.md +51 -0
- data/Gemfile +4 -0
- data/LICENSE.txt +1 -1
- data/README.md +236 -48
- data/dox.gemspec +18 -16
- data/exe/dox +3 -0
- data/infinum.png +0 -0
- data/lib/dox.rb +12 -5
- data/lib/dox/config.rb +3 -5
- data/lib/dox/dsl/attr_proxy.rb +1 -1
- data/lib/dox/dsl/documentation.rb +1 -1
- data/lib/dox/entities/action.rb +31 -5
- data/lib/dox/entities/example.rb +45 -12
- data/lib/dox/formatter.rb +66 -42
- data/lib/dox/printers/action_printer.rb +24 -8
- data/lib/dox/printers/base_printer.rb +10 -7
- data/lib/dox/printers/document_printer.rb +0 -2
- data/lib/dox/printers/example_printer.rb +78 -9
- data/lib/dox/printers/resource_group_printer.rb +12 -3
- data/lib/dox/printers/resource_printer.rb +12 -3
- data/lib/dox/util/http.rb +11 -0
- data/lib/dox/version.rb +1 -1
- metadata +42 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: e3696fee9fddea2f824f129a0a25e61383b01cec
|
4
|
+
data.tar.gz: c69809b3ce6618fc593dd8897938e5f34d8788c9
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 28f6f85ab7471792a741658f83a1a1b522359da8bed3e4bd5f9e9a4cf71d9e28e80fe1a087fc459bd9c4c58afbde4cb797ceb0732d7a3980556c2c973bf7838e
|
7
|
+
data.tar.gz: 2e71c5e388fc0c7bb727f057219e6376b4a2fe80a645738fef539ced75d1099227a27c8ac786b2c8c160c98e99fc99b22a2e0404dc414d7b3a0f2276b1e9bd7a
|
data/.rubocop.yml
ADDED
data/.ruby-version
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
2.3.1
|
data/.travis.yml
CHANGED
@@ -1,4 +1,25 @@
|
|
1
1
|
language: ruby
|
2
|
-
rvm:
|
3
|
-
- 2.3.0
|
4
2
|
before_install: gem install bundler -v 1.11.2
|
3
|
+
|
4
|
+
matrix:
|
5
|
+
include:
|
6
|
+
- rvm: 2.0.0
|
7
|
+
env: "RAILS_VERSION=4.0.0"
|
8
|
+
- rvm: 2.1.2
|
9
|
+
env: "RAILS_VERSION=4.1.0"
|
10
|
+
- rvm: 2.2.0
|
11
|
+
env: "RAILS_VERSION=4.2.0"
|
12
|
+
- rvm: 2.2.2
|
13
|
+
env: "RAILS_VERSION=5.0.0"
|
14
|
+
- rvm: 2.3.0
|
15
|
+
env: "RAILS_VERSION=5.0.0"
|
16
|
+
- rvm: 2.4.0
|
17
|
+
env: "RAILS_VERSION=5.0.0"
|
18
|
+
|
19
|
+
addons:
|
20
|
+
code_climate:
|
21
|
+
repo_token:
|
22
|
+
secure: "LsnC+ru4oLhNOo0YFUfQeVvnCLkfeOv7xN9xSaBO2J1K2qZCadjsX/gnV6BRU5wmAxyXR2xQGnI+9wi4dqlPcuXlTIbE4Ge91WoTU+DNjA8RBrYePfVGsNeuT5wos6I0nBmnNYujBS6Rk0ntc1WEV2nq+3K4dpiTNcAYtS1f8zwV7qXBU63hc3urL0tO6DQUIYOi1rlse2EO5vhBlm3dH24TqEz32RROxh0kkuNLPmoq9NHCZQuJl1I0D3ovW+NRcOYDcgALX4HMRk8+4Hoqz3gyalLNvFujBdwnObL6kiMdRuUO8SGIc2crVMdckAnDBOkYYO4GQUwPv4qzaSX15i8Hrdxz16Rh9saqmX7qacornatt85j0aXA7nDPTD2zxG749XPu1DsUz0VC/2vWbCFhk9VysVtiY/grcUXg1CC/uh0+xbrnZol4rlInXyuXxmWOKThzMeSPjR0aCkQwqpRWG9ck0VTQIcC2mPGIF4o6fsMYe6iDtwPixNsCHBTPa/Ack0rgnxCvb5SH59VK0p4bTgzY/st85mBht1t46sqkbhdDI0S/oJu0NgmpyBAB6RL/kjNlVHvSi4plQxhW2N0FyQpwnLGkvxidIRwqnd1YalJxja2RDe7LaB82zusX+GLl0T79tW4VGEm8PqC7i3COMsWji8P75eiVzvwISN8w="
|
23
|
+
|
24
|
+
after_success:
|
25
|
+
- bundle exec codeclimate-test-reporter
|
data/CHANGES.md
ADDED
@@ -0,0 +1,51 @@
|
|
1
|
+
# Changelog
|
2
|
+
|
3
|
+
## Version 1.0.0
|
4
|
+
|
5
|
+
Released on May 6, 2017
|
6
|
+
|
7
|
+
New:
|
8
|
+
- Guess path params for URI definition from example's request object
|
9
|
+
- Validate HTTP verbs specified in the descriptors' actions
|
10
|
+
- Document only examples whitelisted with `dox` tag
|
11
|
+
- Added option for whitelisting additional HTTP headers for examples
|
12
|
+
- Show request HTTP verb and fullpath for each action request
|
13
|
+
- Dox executable
|
14
|
+
|
15
|
+
Fix:
|
16
|
+
- Ignore body in query params (Rails 4 issue) for example request URL
|
17
|
+
- Pull request and response objects from example metadata
|
18
|
+
|
19
|
+
## Version 1.0.0.alpha
|
20
|
+
|
21
|
+
Released on October 18, 2016
|
22
|
+
|
23
|
+
- Updated the dependencies
|
24
|
+
|
25
|
+
New:
|
26
|
+
- Raise errors on missing required dox attributes in descriptors
|
27
|
+
- `extend Dox::DSL::Syntax` instead of `include Dox::DSL::Syntax` in descriptors
|
28
|
+
|
29
|
+
|
30
|
+
## Version 0.0.3
|
31
|
+
|
32
|
+
Released on June 22, 2016
|
33
|
+
|
34
|
+
Fix:
|
35
|
+
- Fixed example identifier for examples with query params
|
36
|
+
|
37
|
+
|
38
|
+
## Version 0.0.2
|
39
|
+
|
40
|
+
|
41
|
+
Released on June 14, 2016
|
42
|
+
|
43
|
+
- Created core classes and a DSL for manipulating the examples in specs
|
44
|
+
- Added usage to readme
|
45
|
+
|
46
|
+
|
47
|
+
## Version 0.0.1
|
48
|
+
|
49
|
+
Released on June 06, 2016
|
50
|
+
|
51
|
+
- First release of the dox gem where the initial gem skeleton has been created
|
data/Gemfile
CHANGED
data/LICENSE.txt
CHANGED
data/README.md
CHANGED
@@ -1,114 +1,297 @@
|
|
1
|
+
[![Build Status](https://travis-ci.org/infinum/dox.svg?branch=master)](https://travis-ci.org/infinum/dox)
|
2
|
+
[![Code Climate](https://codeclimate.com/github/infinum/dox/badges/gpa.svg)](https://codeclimate.com/github/infinum/dox)
|
3
|
+
[![Test Coverage](https://codeclimate.com/github/infinum/dox/badges/coverage.svg)](https://codeclimate.com/github/infinum/dox/coverage)
|
4
|
+
|
1
5
|
# Dox
|
2
6
|
|
3
|
-
Dox formats the
|
7
|
+
Automate your documentation writing proces! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the tests output in the [API Blueprint](https://apiblueprint.org) format. Choose one of the [renderes](#renderers) to convert it to HTML or host it on [Apiary.io](https://apiary.io)
|
8
|
+
|
9
|
+
Here's a [demo app](https://github.com/infinum/dox-demo) and here are some examples:
|
10
|
+
|
11
|
+
- [Dox demo - Apiary](http://docs.doxdemo.apiary.io/#reference/books/books)
|
12
|
+
- [Dox demo - Aglio](https://infinum.github.io/dox-demo/aglio)
|
13
|
+
- [Dox demo - Snowboard](https://infinum.github.io/dox-demo/snowboard)
|
14
|
+
|
4
15
|
|
5
16
|
## Installation
|
6
17
|
|
7
18
|
Add this line to your application's Gemfile:
|
8
19
|
|
9
20
|
```ruby
|
10
|
-
|
21
|
+
group :test do
|
22
|
+
gem 'dox', require: 'false'
|
23
|
+
end
|
11
24
|
```
|
12
25
|
|
13
26
|
And then execute:
|
14
27
|
|
15
|
-
|
28
|
+
```
|
29
|
+
$ bundle
|
30
|
+
```
|
16
31
|
|
17
32
|
Or install it yourself as:
|
18
33
|
|
19
|
-
|
34
|
+
```
|
35
|
+
$ gem install dox
|
36
|
+
```
|
20
37
|
|
21
38
|
## Usage
|
22
39
|
|
23
|
-
###
|
40
|
+
### Require it
|
41
|
+
Require Dox in the rails_helper:
|
24
42
|
|
25
|
-
|
43
|
+
``` ruby
|
44
|
+
require 'dox'
|
45
|
+
```
|
46
|
+
|
47
|
+
and configure rspec with this:
|
26
48
|
|
27
49
|
``` ruby
|
28
|
-
|
50
|
+
Rspec.configure do |config|
|
51
|
+
config.after(:each, :dox) do |example|
|
52
|
+
example.metadata[:request] = request
|
53
|
+
example.metadata[:response] = response
|
54
|
+
end
|
55
|
+
end
|
56
|
+
```
|
57
|
+
|
58
|
+
### Configure it
|
59
|
+
Set these mandatory options in the rails_helper:
|
60
|
+
|
61
|
+
| Option | Value | Description |
|
62
|
+
| -- | -- | -- |
|
63
|
+
| header_file_path | Pathname instance or fullpath string | Markdown file that will be included at the top of the documentation. It should contain title and some basic info about the api. |
|
64
|
+
| desc_folder_path | Pathname instance or fullpath string | Folder with markdown descriptions. |
|
65
|
+
|
66
|
+
|
67
|
+
Optional settings:
|
68
|
+
|
69
|
+
| Option | Value| Description |
|
70
|
+
| -- | -- | -- |
|
71
|
+
| headers_whitelist | Array of headers (strings) | Requests and responses will by default list only `Content-Type` header. To list other http headers, you must whitelist them.|
|
72
|
+
|
73
|
+
Example:
|
74
|
+
|
75
|
+
``` ruby
|
76
|
+
Dox.configure do |config|
|
77
|
+
config.header_file_path = Rails.root.join('spec/docs/v1/descriptions/header.md')
|
78
|
+
config.desc_folder_path = Rails.root.join('spec/docs/v1/descriptions')
|
79
|
+
config.headers_whitelist = ['Accept', 'X-Auth-Token']
|
80
|
+
end
|
81
|
+
```
|
82
|
+
|
83
|
+
### Basic example
|
84
|
+
|
85
|
+
Define a descriptor module for a resource using Dox DSL:
|
86
|
+
|
87
|
+
``` ruby
|
88
|
+
module Docs
|
29
89
|
module V1
|
30
90
|
module Bids
|
31
|
-
|
91
|
+
extend Dox::DSL::Syntax
|
32
92
|
|
93
|
+
# define common resource data for each action
|
33
94
|
document :api do
|
34
|
-
|
35
|
-
name 'Bids'
|
36
|
-
end
|
37
|
-
|
38
|
-
resource do
|
39
|
-
name 'Bids'
|
95
|
+
resource 'Bids' do
|
40
96
|
endpoint '/bids'
|
41
97
|
group 'Bids'
|
42
|
-
desc 'bid_resource.md'
|
43
98
|
end
|
44
99
|
end
|
45
100
|
|
101
|
+
# define data for specific action
|
46
102
|
document :index do
|
47
|
-
action
|
48
|
-
name 'Get bids'
|
49
|
-
verb 'GET'
|
50
|
-
path '/bids'
|
51
|
-
desc 'Returns list of user bids'
|
52
|
-
end
|
53
|
-
end
|
54
|
-
|
55
|
-
document :create do
|
56
|
-
action do
|
57
|
-
name 'Post bids'
|
58
|
-
verb 'POST'
|
59
|
-
path '/bids'
|
60
|
-
desc 'Creates bid'
|
61
|
-
end
|
103
|
+
action 'Get bids'
|
62
104
|
end
|
63
105
|
end
|
64
106
|
end
|
65
107
|
end
|
108
|
+
|
109
|
+
```
|
110
|
+
<small>You can define the descriptors for example in specs/docs folder, just make sure you load them in the rails_helper.rb:
|
111
|
+
|
112
|
+
``` ruby
|
113
|
+
Dir[Rails.root.join('spec/docs/**/*.rb')].each { |f| require f }
|
66
114
|
```
|
67
|
-
|
115
|
+
</small>
|
68
116
|
|
69
|
-
|
117
|
+
Include the descriptor modules in a controller and tag the specs you want to document with **dox**:
|
70
118
|
|
71
119
|
``` ruby
|
72
120
|
describe Api::V1::BidsController, type: :controller do
|
73
|
-
include
|
121
|
+
# include resource module
|
122
|
+
include Docs::V1::Bids::Api
|
74
123
|
|
75
124
|
describe 'GET #index' do
|
76
|
-
include
|
125
|
+
# include action module
|
126
|
+
include Docs::V1::Bids::Index
|
77
127
|
|
78
|
-
it 'returns a list of bids' do
|
128
|
+
it 'returns a list of bids', :dox do
|
79
129
|
get :index
|
80
130
|
expect(response).to have_http_status(:ok)
|
81
131
|
end
|
132
|
+
end
|
133
|
+
end
|
134
|
+
```
|
135
|
+
|
136
|
+
And [generate the documentation](#generate-documentation).
|
137
|
+
|
138
|
+
|
139
|
+
### Advanced options
|
140
|
+
|
141
|
+
Before running into any more details, here's roughly how is the generated API Blueprint document structured:
|
82
142
|
|
143
|
+
- header
|
144
|
+
- resource group
|
145
|
+
- resource
|
146
|
+
- action
|
147
|
+
- example 1
|
148
|
+
- example 2
|
149
|
+
- action
|
150
|
+
- ...
|
151
|
+
- resource
|
152
|
+
- action
|
153
|
+
- ...
|
154
|
+
- resource group
|
155
|
+
- resource
|
156
|
+
- action
|
157
|
+
|
158
|
+
|
159
|
+
Header is defined in a markdown file as mentioned before. Examples are concrete test examples (you can have 2 examples for create 1 happy path, 1 fail path). They are completely automatically generated from the request/response objects.
|
160
|
+
And you can customize the following in the descriptors:
|
161
|
+
|
162
|
+
- resource group
|
163
|
+
- resource
|
164
|
+
- action
|
165
|
+
|
166
|
+
#### Resource group
|
167
|
+
|
168
|
+
Resource group contains related resources and is defined with:
|
169
|
+
- **name** (required)
|
170
|
+
- desc (optional, inline string or relative filepath)
|
171
|
+
|
172
|
+
Example:
|
173
|
+
``` ruby
|
174
|
+
document :bids_group do
|
175
|
+
group 'Bids' do
|
176
|
+
desc 'Here are all bid related resources'
|
177
|
+
end
|
178
|
+
end
|
179
|
+
```
|
180
|
+
|
181
|
+
You can omit defining the resource group, if you don't have any description for it. Related resources will be linked in a group by the group option at the resource definition.
|
182
|
+
|
183
|
+
#### Resource
|
184
|
+
Resource contains actions and is defined with:
|
185
|
+
- **name** (required)
|
186
|
+
- **endpoint** (required)
|
187
|
+
- **group** (required; to associate it with the related group)
|
188
|
+
- desc (optional; inline string or relative filepath)
|
189
|
+
|
190
|
+
Example:
|
191
|
+
``` ruby
|
192
|
+
document :bids do
|
193
|
+
resource 'Bids' do
|
194
|
+
endpoint '/bids'
|
195
|
+
group 'Bids'
|
196
|
+
desc 'bids/bids.md'
|
83
197
|
end
|
84
198
|
end
|
85
199
|
```
|
86
200
|
|
87
|
-
|
201
|
+
Usually you'll want to define resource and resource group together, so you don't have to include 2 modules with common data per spec file:
|
88
202
|
|
89
|
-
|
203
|
+
``` ruby
|
204
|
+
document :bids_common do
|
205
|
+
group 'Bids' do
|
206
|
+
desc 'Here are all bid related resources'
|
207
|
+
end
|
90
208
|
|
91
|
-
|
209
|
+
resource 'Bids' do
|
210
|
+
endpoint '/bids'
|
211
|
+
group 'Bids'
|
212
|
+
desc 'bids/bids.md'
|
213
|
+
end
|
214
|
+
end
|
215
|
+
```
|
216
|
+
|
217
|
+
#### Action
|
218
|
+
Action is defined with:
|
219
|
+
- **name** (required)
|
220
|
+
- path* (optional)
|
221
|
+
- verb* (optional)
|
222
|
+
- params* (optional)
|
223
|
+
- desc (optional; inline string or relative filepath)
|
92
224
|
|
93
|
-
|
225
|
+
\* these optional attributes are guessed (if not defined) from the request object of the test example and you can override them.
|
226
|
+
|
227
|
+
Example:
|
94
228
|
|
95
229
|
``` ruby
|
96
|
-
|
97
|
-
|
98
|
-
|
230
|
+
show_params = { id: { type: :number, required: :required, value: 1, description: 'bid id' } }
|
231
|
+
|
232
|
+
document :action do
|
233
|
+
action 'Get bid' do
|
234
|
+
path '/bids/{id}'
|
235
|
+
verb 'GET'
|
236
|
+
params show_params
|
237
|
+
desc 'Some description for get bid action'
|
238
|
+
end
|
99
239
|
end
|
100
240
|
```
|
101
241
|
|
102
|
-
### Generate
|
103
|
-
|
242
|
+
### Generate documentation
|
243
|
+
Documentation is generated in 2 steps:
|
244
|
+
|
245
|
+
1. generate API Blueprint markdown with dox command:
|
246
|
+
```bundle exec dox spec/controllers/api/v1 > docs.md```
|
247
|
+
|
248
|
+
2. render HTML with some renderer, for example, with Aglio:
|
249
|
+
```aglio -i docs.md -o docs.html```
|
250
|
+
|
251
|
+
|
252
|
+
#### Renderers
|
253
|
+
You can render the HTML yourself with one of the renderers:
|
254
|
+
|
255
|
+
- [Aglio](https://github.com/danielgtaylor/aglio)
|
256
|
+
- [Snowboard](https://github.com/subosito/snowboard)
|
257
|
+
|
258
|
+
Both support multiple themes and template customization.
|
259
|
+
|
260
|
+
Or you can just take your generated markdown and host your documentation on [Apiary.io](https://apiary.io).
|
261
|
+
|
262
|
+
|
263
|
+
### Common issues
|
264
|
+
|
265
|
+
You might experience some strange issues when generating the documentation. Here are a few examples of what we've encountered so far.
|
104
266
|
|
105
|
-
|
267
|
+
#### Wrap parameters issue
|
268
|
+
Rails wraps JSON parameters on all requests by default, which results with documented requests looking like this:
|
269
|
+
|
270
|
+
```
|
271
|
+
+ Request get pokemons
|
272
|
+
{
|
273
|
+
"pokemon": {}
|
274
|
+
}
|
275
|
+
```
|
276
|
+
|
277
|
+
To disable wrapping parameters with a resource name, turn off this feature in `config/initializers/wrap_parameters.rb`:
|
106
278
|
|
107
279
|
``` ruby
|
108
|
-
|
109
|
-
|
280
|
+
# Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array.
|
281
|
+
ActiveSupport.on_load(:action_controller) do
|
282
|
+
wrap_parameters format: []
|
283
|
+
end
|
110
284
|
```
|
111
285
|
|
286
|
+
#### Rendering warnings with Aglio
|
287
|
+
You might get the following warnings when rendering HTML with Aglio:
|
288
|
+
|
289
|
+
* `no headers specified (warning code 3)`
|
290
|
+
* `empty request message-body (warning code 6)`
|
291
|
+
|
292
|
+
This usually happens on GET requests examples when there are no headers. To solve this issue, add at least one header to the tests' requests, like `Accept: application/json`.
|
293
|
+
|
294
|
+
|
112
295
|
## Development
|
113
296
|
|
114
297
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
@@ -117,8 +300,13 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
|
|
117
300
|
|
118
301
|
## Contributing
|
119
302
|
|
120
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/
|
303
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/infinum/dox. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
304
|
+
|
305
|
+
|
306
|
+
## Credits
|
307
|
+
Dox is maintained and sponsored by [Infinum](https://infinum.co).
|
121
308
|
|
309
|
+
<a href="https://infinum.co"><img alt="Infinum" src="infinum.png" width="250"></a>
|
122
310
|
|
123
311
|
## License
|
124
312
|
|