Skip to content

Commit 3f212a8

Browse files
LeFnordLeFnord
committed
corrects documentation of versions (ruby-grape#405)
1 parent c782b5b commit 3f212a8

14 files changed

+196
-40
lines changed

‎.travis.yml

+2-5
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,14 @@ language: ruby
33
sudo: false
44

55
rvm:
6-
- 2.3.0
7-
- 2.2.3
8-
- 2.1.7
9-
- jruby-19mode
6+
- 2.3.1
7+
- 2.2.5
108
- jruby-9.0.5.0
119
- rbx-2
1210

1311
matrix:
1412
allow_failures:
1513
- rvm: rbx-2
16-
- rvm: jruby-19mode
1714
env:
1815
- GRAPE_VERSION=0.12.0
1916
- GRAPE_VERSION=0.13.0

‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
#### Fixes
66

7+
* [#405](https://github.com/ruby-grape/grape-swagger/pull/405): corrects documentation of versions [issue #403](https://github.com/ruby-grape/grape-swagger/issues/403) - [@LeFnord](https://github.com/LeFnord).
78
* [#399](https://github.com/ruby-grape/grape-swagger/pull/399): makes param description optional, solves [issue #395](https://github.com/ruby-grape/grape-swagger/issues/395) - [@LeFnord](https://github.com/LeFnord).
89

910

‎README.md

+16-16
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,8 @@ end
123123
* [mount_path](#mount_path)
124124
* [add_base_path](#add_base_path)
125125
* [add_version](#add_version)
126+
* [doc_version](#doc_version)
126127
* [markdown](#markdown)
127-
* [api_version](#api_version)
128128
* [models](#models)
129129
* [hide_documentation_path](#hide_documentation_path)
130130
* [info](#info)
@@ -139,42 +139,51 @@ You can pass a hash with optional configuration settings to ```add_swagger_docum
139139
140140
<a name="host" />
141141
#### host:
142-
Sets explicit the `host`
142+
Sets explicit the `host`, default would be taken from `request`.
143143
```ruby
144144
add_swagger_documentation \
145-
host: 'www.no-example.com'
145+
host: 'www.example.com'
146146
```
147147

148148
<a name="base_path" />
149149
#### base_path:
150-
Base path of the API that's being exposed.
150+
Base path of the API that's being exposed, default would be taken from `request`.
151151
```ruby
152152
add_swagger_documentation \
153153
base_path: '/super/api'
154154
```
155155
156156
<a name="mount_path" />
157157
#### mount_path:
158-
The path where the API documentation is loaded, default is `/swagger_doc`.
158+
The path where the API documentation is loaded, default is: `/swagger_doc`.
159159
```ruby
160160
add_swagger_documentation \
161161
mount_path: '/docu'
162162
```
163163
164164
#### add_base_path:
165-
Add `basePath` key to the JSON documentation, default is `false`.
165+
Add `basePath` key to the documented path keys, default is: `false`.
166166
```ruby
167167
add_swagger_documentation \
168168
add_base_path: true
169169
```
170170
171171
#### add_version:
172-
Add `version` key to the JSON documentation, default is `true`.
172+
Add `version` key to the documented path keys, default is: `true`,
173+
here the version is the API version, specified by `grape` in [`path`](https://github.com/ruby-grape/grape/#path)
174+
173175
```ruby
174176
add_swagger_documentation \
175177
add_version: false
176178
```
177179
180+
<a name="doc_version" />
181+
#### doc_version:
182+
Specify the version of the documentation at [info section](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object), default is: `'0.0.1'`
183+
```ruby
184+
add_swagger_documentation \
185+
doc_version: '0.0.1'
186+
```
178187
179188
<a name="markdown" />
180189
#### markdown:
@@ -190,15 +199,6 @@ add_swagger_documentation \
190199
markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
191200
```
192201
193-
<a name="api_version" />
194-
#### api_version:
195-
```ruby
196-
add_swagger_documentation \
197-
api_version: 'v1'
198-
```
199-
200-
Version of the API that's being exposed.
201-
202202
203203
#### *authorizations*:
204204
This value is added to the `authorizations` key in the JSON documentation.

‎lib/grape-swagger/doc_methods.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ def defaults
9191
{
9292
info: {},
9393
models: [],
94-
api_version: 'v1',
94+
doc_version: '0.0.1',
9595
target_class: nil,
9696
mount_path: '/swagger_doc',
9797
host: nil,

‎lib/grape-swagger/doc_methods/path_string.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ def build(path, options = {})
1414
item = path.gsub(%r{/{(.+?)}}, '').split('/').last.singularize.underscore.camelize || 'Item'
1515

1616
if options[:version] && options[:add_version]
17-
path.sub!('{version}', options[:version])
17+
path.sub!('{version}', options[:version].to_s)
1818
else
1919
path.sub!('/{version}', '')
2020
end

‎lib/grape-swagger/endpoint.rb

+2-2
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ def content_types_for(target_class)
2020
# required keys for SwaggerObject
2121
def swagger_object(target_class, request, options)
2222
{
23-
info: info_object(options[:info].merge(version: options[:api_version])),
23+
info: info_object(options[:info].merge(version: options[:doc_version])),
2424
swagger: '2.0',
2525
produces: content_types_for(target_class),
2626
authorizations: options[:authorizations],
@@ -109,7 +109,7 @@ def method_object(route, options, path)
109109
method[:consumes] = consumes_object(route, options[:format])
110110
method[:parameters] = params_object(route)
111111
method[:responses] = response_object(route, options[:markdown])
112-
method[:tags] = tag_object(route, options[:version])
112+
method[:tags] = tag_object(route, options[:version].to_s)
113113
method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
114114
method.delete_if { |_, value| value.blank? }
115115
end

‎spec/issues/403_versions_spec.rb

+157
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
require 'spec_helper'
2+
3+
describe 'describing versions' do
4+
describe 'nothings given' do
5+
def app
6+
Class.new(Grape::API) do
7+
desc 'no versions given'
8+
get '/nothings' do
9+
{ message: 'hello world …'}
10+
end
11+
12+
add_swagger_documentation format: :json
13+
end
14+
end
15+
16+
subject do
17+
get '/swagger_doc'
18+
JSON.parse(last_response.body , symbolize_names: true)
19+
end
20+
21+
specify do
22+
expect(subject).to eql({
23+
info: {title: "API title", version: "0.0.1"},
24+
swagger: "2.0",
25+
produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
26+
host: "example.org",
27+
tags: [{name: "nothings", description: "Operations about nothings"}],
28+
paths: {
29+
'/nothings': {
30+
get: {
31+
description: "no versions given",
32+
produces: ["application/json"],
33+
responses: {
34+
'200': {description: "no versions given"}
35+
},
36+
tags: ["nothings"],
37+
operationId: "getNothings"
38+
}}}})
39+
end
40+
end
41+
42+
describe 'API version given' do
43+
def app
44+
Class.new(Grape::API) do
45+
version 'v2', using: :path
46+
desc 'api versions given'
47+
get '/api_version' do
48+
{ message: 'hello world …'}
49+
end
50+
51+
add_swagger_documentation format: :json
52+
end
53+
end
54+
55+
subject do
56+
get '/v2/swagger_doc'
57+
JSON.parse(last_response.body , symbolize_names: true)
58+
end
59+
60+
specify do
61+
expect(subject).to eql({
62+
info: {title: "API title", version: "0.0.1"},
63+
swagger: "2.0",
64+
produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
65+
host: "example.org",
66+
tags: [{name: "api_version", description: "Operations about api_versions"}],
67+
paths: {
68+
'/v2/api_version': {
69+
get: {
70+
description: "api versions given",
71+
produces: ["application/json"],
72+
responses: {
73+
'200': {description: "api versions given"}
74+
},
75+
tags: ["api_version"],
76+
operationId: "getV2ApiVersion"
77+
}}}})
78+
end
79+
end
80+
81+
describe 'DOC version given' do
82+
def app
83+
Class.new(Grape::API) do
84+
desc 'doc versions given'
85+
get '/doc_version' do
86+
{ message: 'hello world …'}
87+
end
88+
89+
add_swagger_documentation doc_version: '0.0.2'
90+
end
91+
end
92+
93+
subject do
94+
get '/swagger_doc'
95+
JSON.parse(last_response.body , symbolize_names: true)
96+
end
97+
98+
specify do
99+
expect(subject).to eql({
100+
info: {title: "API title", version: "0.0.2"},
101+
swagger: "2.0",
102+
produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
103+
host: "example.org",
104+
tags: [{name: "doc_version", description: "Operations about doc_versions"}],
105+
paths: {
106+
'/doc_version': {
107+
get: {
108+
description: "doc versions given",
109+
produces: ["application/json"],
110+
responses: {
111+
'200': {description: "doc versions given"}
112+
},
113+
tags: ["doc_version"],
114+
operationId: "getDocVersion"
115+
}}}})
116+
end
117+
end
118+
119+
describe 'both versions given' do
120+
def app
121+
Class.new(Grape::API) do
122+
version :v2, using: :path
123+
desc 'both versions given'
124+
get '/both_versions' do
125+
{ message: 'hello world …'}
126+
end
127+
128+
add_swagger_documentation doc_version: '0.0.2'
129+
end
130+
end
131+
132+
subject do
133+
get '/v2/swagger_doc'
134+
JSON.parse(last_response.body , symbolize_names: true)
135+
end
136+
137+
specify do
138+
expect(subject).to eql({
139+
info: {title: "API title", version: "0.0.2"},
140+
swagger: "2.0",
141+
produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
142+
host: "example.org",
143+
tags: [{name: "both_versions", description: "Operations about both_versions"}],
144+
paths: {
145+
'/v2/both_versions': {
146+
get: {
147+
description: "both versions given",
148+
produces: ["application/json"],
149+
responses: {
150+
'200': {description: "both versions given"}
151+
},
152+
tags: ["both_versions"],
153+
operationId: "getV2BothVersions"
154+
}}}})
155+
end
156+
end
157+
end

‎spec/support/api_swagger_v2_result.rb

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ class ApiError < Grape::Entity
6767
"termsOfServiceUrl"=>"www.The-URL-of-the-terms-and-service.com",
6868
"contact"=>{"name"=>"Contact name", "email"=>"[email protected]", "url"=>"Contact URL"},
6969
"license"=>{"name"=>"The name of the license.", "url"=>"www.The-URL-of-the-license.org"},
70-
"version"=>"v1"
70+
"version"=>"0.0.1"
7171
},
7272
"swagger"=>"2.0",
7373
"produces"=>["application/json"],

‎spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb

+2-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ class ConfigurationApi < Grape::API
1818
end
1919

2020
add_swagger_documentation format: :json,
21-
api_version: '23',
21+
doc_version: '23',
2222
schemes: 'https',
2323
host: -> { 'another.host.com' },
2424
base_path: -> { 'somewhere/over/the/rainbow' },
@@ -41,6 +41,7 @@ def app
4141
end
4242

4343
specify do
44+
expect(subject['info']['version']).to eql '23'
4445
expect(subject['host']).to eql 'another.host.com'
4546
expect(subject['basePath']).to eql 'somewhere/over/the/rainbow'
4647
expect(subject['paths'].keys.first).to eql '/somewhere/over/the/rainbow/v3/configuration'

‎spec/swagger_v2/api_swagger_v2_response_spec.rb

+3-3
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ def app
4646
end
4747
specify do
4848
expect(subject).to eql({
49-
"info"=>{"title"=>"API title", "version"=>"v1"},
49+
"info"=>{"title"=>"API title", "version"=>"0.0.1"},
5050
"swagger"=>"2.0",
5151
"produces"=>["application/json"],
5252
"host"=>"example.org",
@@ -94,7 +94,7 @@ def app
9494

9595
specify do
9696
expect(subject).to eql({
97-
"info"=>{"title"=>"API title", "version"=>"v1"},
97+
"info"=>{"title"=>"API title", "version"=>"0.0.1"},
9898
"swagger"=>"2.0",
9999
"produces"=>["application/json"],
100100
"host"=>"example.org",
@@ -139,7 +139,7 @@ def app
139139

140140
specify do
141141
expect(subject).to eql({
142-
"info"=>{"title"=>"API title", "version"=>"v1"},
142+
"info"=>{"title"=>"API title", "version"=>"0.0.1"},
143143
"swagger"=>"2.0",
144144
"produces"=>["application/json"],
145145
"host"=>"example.org",

‎spec/swagger_v2/default_api_spec.rb

+2-2
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ def app
2222
it 'documents api' do
2323
expect(subject).to eq(
2424
{
25-
"info"=>{"title"=>"API title", "version"=>"v1"},
25+
"info"=>{"title"=>"API title", "version"=>"0.0.1"},
2626
"swagger"=>"2.0",
2727
"produces"=>["application/json"],
2828
"host"=>"example.org",
@@ -66,7 +66,7 @@ def app
6666

6767
it 'documents endpoint' do
6868
expect(subject).to eq({
69-
"info"=>{"title"=>"API title", "version"=>"v1"},
69+
"info"=>{"title"=>"API title", "version"=>"0.0.1"},
7070
"swagger"=>"2.0",
7171
"produces"=>["application/json"],
7272
"host"=>"example.org",

0 commit comments

Comments
 (0)