diff --git a/.travis.yml b/.travis.yml
index 8e77265f..ddd9aae9 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -3,17 +3,14 @@ language: ruby
sudo: false
rvm:
- - 2.3.0
- - 2.2.3
- - 2.1.7
- - jruby-19mode
+ - 2.3.1
+ - 2.2.5
- jruby-9.0.5.0
- rbx-2
matrix:
allow_failures:
- rvm: rbx-2
- - rvm: jruby-19mode
env:
- GRAPE_VERSION=0.12.0
- GRAPE_VERSION=0.13.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16268636..3ab86145 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
#### Fixes
+* [#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).
* [#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).
diff --git a/README.md b/README.md
index 86fc7bc0..63d73913 100644
--- a/README.md
+++ b/README.md
@@ -123,8 +123,8 @@ end
* [mount_path](#mount_path)
* [add_base_path](#add_base_path)
* [add_version](#add_version)
+* [doc_version](#doc_version)
* [markdown](#markdown)
-* [api_version](#api_version)
* [models](#models)
* [hide_documentation_path](#hide_documentation_path)
* [info](#info)
@@ -139,15 +139,15 @@ You can pass a hash with optional configuration settings to ```add_swagger_docum
#### host:
-Sets explicit the `host`
+Sets explicit the `host`, default would be taken from `request`.
```ruby
add_swagger_documentation \
- host: 'www.no-example.com'
+ host: 'www.example.com'
```
#### base_path:
-Base path of the API that's being exposed.
+Base path of the API that's being exposed, default would be taken from `request`.
```ruby
add_swagger_documentation \
base_path: '/super/api'
@@ -155,26 +155,38 @@ add_swagger_documentation \
#### mount_path:
-The path where the API documentation is loaded, default is `/swagger_doc`.
+The path where the API documentation is loaded, default is: `/swagger_doc`.
```ruby
add_swagger_documentation \
mount_path: '/docu'
```
#### add_base_path:
-Add `basePath` key to the JSON documentation, default is `false`.
+Add `basePath` key to the documented path keys, default is: `false`.
```ruby
add_swagger_documentation \
add_base_path: true
```
#### add_version:
-Add `version` key to the JSON documentation, default is `true`.
+Add `version` key to the documented path keys, default is: `true`,
+here the version is the API version, specified by `grape` in [`path`](https://github.com/ruby-grape/grape/#path)
+
```ruby
add_swagger_documentation \
add_version: false
```
+
+#### doc_version:
+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'`
+```ruby
+add_swagger_documentation \
+ doc_version: '0.0.1'
+```
+
+Version of the API that's being exposed.
+
#### markdown:
@@ -190,15 +202,6 @@ add_swagger_documentation \
markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
```
-
-#### api_version:
-```ruby
-add_swagger_documentation \
- api_version: 'v1'
-```
-
-Version of the API that's being exposed.
-
#### *authorizations*:
This value is added to the `authorizations` key in the JSON documentation.
diff --git a/lib/grape-swagger/doc_methods.rb b/lib/grape-swagger/doc_methods.rb
index 34f3fa73..b6da88ed 100644
--- a/lib/grape-swagger/doc_methods.rb
+++ b/lib/grape-swagger/doc_methods.rb
@@ -91,7 +91,7 @@ def defaults
{
info: {},
models: [],
- api_version: 'v1',
+ doc_version: '0.0.1',
target_class: nil,
mount_path: '/swagger_doc',
host: nil,
diff --git a/lib/grape-swagger/doc_methods/path_string.rb b/lib/grape-swagger/doc_methods/path_string.rb
index 051607a5..36fd4481 100644
--- a/lib/grape-swagger/doc_methods/path_string.rb
+++ b/lib/grape-swagger/doc_methods/path_string.rb
@@ -14,7 +14,7 @@ def build(path, options = {})
item = path.gsub(%r{/{(.+?)}}, '').split('/').last.singularize.underscore.camelize || 'Item'
if options[:version] && options[:add_version]
- path.sub!('{version}', options[:version])
+ path.sub!('{version}', options[:version].to_s)
else
path.sub!('/{version}', '')
end
diff --git a/lib/grape-swagger/endpoint.rb b/lib/grape-swagger/endpoint.rb
index b0e56bb2..4772fc83 100644
--- a/lib/grape-swagger/endpoint.rb
+++ b/lib/grape-swagger/endpoint.rb
@@ -20,7 +20,7 @@ def content_types_for(target_class)
# required keys for SwaggerObject
def swagger_object(target_class, request, options)
{
- info: info_object(options[:info].merge(version: options[:api_version])),
+ info: info_object(options[:info].merge(version: options[:doc_version])),
swagger: '2.0',
produces: content_types_for(target_class),
authorizations: options[:authorizations],
@@ -109,7 +109,7 @@ def method_object(route, options, path)
method[:consumes] = consumes_object(route, options[:format])
method[:parameters] = params_object(route)
method[:responses] = response_object(route, options[:markdown])
- method[:tags] = tag_object(route, options[:version])
+ method[:tags] = tag_object(route, options[:version].to_s)
method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
method.delete_if { |_, value| value.blank? }
end
diff --git a/spec/issues/403_versions_spec.rb b/spec/issues/403_versions_spec.rb
new file mode 100644
index 00000000..889fa9a8
--- /dev/null
+++ b/spec/issues/403_versions_spec.rb
@@ -0,0 +1,157 @@
+require 'spec_helper'
+
+describe 'describing versions' do
+ describe 'nothings given' do
+ def app
+ Class.new(Grape::API) do
+ desc 'no versions given'
+ get '/nothings' do
+ { message: 'hello world …'}
+ end
+
+ add_swagger_documentation format: :json
+ end
+ end
+
+ subject do
+ get '/swagger_doc'
+ JSON.parse(last_response.body , symbolize_names: true)
+ end
+
+ specify do
+ expect(subject).to eql({
+ info: {title: "API title", version: "0.0.1"},
+ swagger: "2.0",
+ produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
+ host: "example.org",
+ tags: [{name: "nothings", description: "Operations about nothings"}],
+ paths: {
+ '/nothings': {
+ get: {
+ description: "no versions given",
+ produces: ["application/json"],
+ responses: {
+ '200': {description: "no versions given"}
+ },
+ tags: ["nothings"],
+ operationId: "getNothings"
+ }}}})
+ end
+ end
+
+ describe 'API version given' do
+ def app
+ Class.new(Grape::API) do
+ version 'v2', using: :path
+ desc 'api versions given'
+ get '/api_version' do
+ { message: 'hello world …'}
+ end
+
+ add_swagger_documentation format: :json
+ end
+ end
+
+ subject do
+ get '/v2/swagger_doc'
+ JSON.parse(last_response.body , symbolize_names: true)
+ end
+
+ specify do
+ expect(subject).to eql({
+ info: {title: "API title", version: "0.0.1"},
+ swagger: "2.0",
+ produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
+ host: "example.org",
+ tags: [{name: "api_version", description: "Operations about api_versions"}],
+ paths: {
+ '/v2/api_version': {
+ get: {
+ description: "api versions given",
+ produces: ["application/json"],
+ responses: {
+ '200': {description: "api versions given"}
+ },
+ tags: ["api_version"],
+ operationId: "getV2ApiVersion"
+ }}}})
+ end
+ end
+
+ describe 'DOC version given' do
+ def app
+ Class.new(Grape::API) do
+ desc 'doc versions given'
+ get '/doc_version' do
+ { message: 'hello world …'}
+ end
+
+ add_swagger_documentation doc_version: '0.0.2'
+ end
+ end
+
+ subject do
+ get '/swagger_doc'
+ JSON.parse(last_response.body , symbolize_names: true)
+ end
+
+ specify do
+ expect(subject).to eql({
+ info: {title: "API title", version: "0.0.2"},
+ swagger: "2.0",
+ produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
+ host: "example.org",
+ tags: [{name: "doc_version", description: "Operations about doc_versions"}],
+ paths: {
+ '/doc_version': {
+ get: {
+ description: "doc versions given",
+ produces: ["application/json"],
+ responses: {
+ '200': {description: "doc versions given"}
+ },
+ tags: ["doc_version"],
+ operationId: "getDocVersion"
+ }}}})
+ end
+ end
+
+ describe 'both versions given' do
+ def app
+ Class.new(Grape::API) do
+ version :v2, using: :path
+ desc 'both versions given'
+ get '/both_versions' do
+ { message: 'hello world …'}
+ end
+
+ add_swagger_documentation doc_version: '0.0.2'
+ end
+ end
+
+ subject do
+ get '/v2/swagger_doc'
+ JSON.parse(last_response.body , symbolize_names: true)
+ end
+
+ specify do
+ expect(subject).to eql({
+ info: {title: "API title", version: "0.0.2"},
+ swagger: "2.0",
+ produces: ["application/xml", "application/json", "application/octet-stream", "text/plain"],
+ host: "example.org",
+ tags: [{name: "both_versions", description: "Operations about both_versions"}],
+ paths: {
+ '/v2/both_versions': {
+ get: {
+ description: "both versions given",
+ produces: ["application/json"],
+ responses: {
+ '200': {description: "both versions given"}
+ },
+ tags: ["both_versions"],
+ operationId: "getV2BothVersions"
+ }}}})
+ end
+ end
+end
diff --git a/spec/support/api_swagger_v2_result.rb b/spec/support/api_swagger_v2_result.rb
index 6cff88ef..875aea12 100644
--- a/spec/support/api_swagger_v2_result.rb
+++ b/spec/support/api_swagger_v2_result.rb
@@ -67,7 +67,7 @@ class ApiError < Grape::Entity
"termsOfServiceUrl"=>"www.The-URL-of-the-terms-and-service.com",
"contact"=>{"name"=>"Contact name", "email"=>"Contact@email.com", "url"=>"Contact URL"},
"license"=>{"name"=>"The name of the license.", "url"=>"www.The-URL-of-the-license.org"},
- "version"=>"v1"
+ "version"=>"0.0.1"
},
"swagger"=>"2.0",
"produces"=>["application/json"],
diff --git a/spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb b/spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb
index e6053b60..a4210bea 100644
--- a/spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb
+++ b/spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb
@@ -18,7 +18,7 @@ class ConfigurationApi < Grape::API
end
add_swagger_documentation format: :json,
- api_version: '23',
+ doc_version: '23',
schemes: 'https',
host: -> { 'another.host.com' },
base_path: -> { 'somewhere/over/the/rainbow' },
@@ -41,6 +41,7 @@ def app
end
specify do
+ expect(subject['info']['version']).to eql '23'
expect(subject['host']).to eql 'another.host.com'
expect(subject['basePath']).to eql 'somewhere/over/the/rainbow'
expect(subject['paths'].keys.first).to eql '/somewhere/over/the/rainbow/v3/configuration'
diff --git a/spec/swagger_v2/api_swagger_v2_response_spec.rb b/spec/swagger_v2/api_swagger_v2_response_spec.rb
index 7ee55d08..de14f454 100644
--- a/spec/swagger_v2/api_swagger_v2_response_spec.rb
+++ b/spec/swagger_v2/api_swagger_v2_response_spec.rb
@@ -46,7 +46,7 @@ def app
end
specify do
expect(subject).to eql({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/json"],
"host"=>"example.org",
@@ -94,7 +94,7 @@ def app
specify do
expect(subject).to eql({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/json"],
"host"=>"example.org",
@@ -139,7 +139,7 @@ def app
specify do
expect(subject).to eql({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/json"],
"host"=>"example.org",
diff --git a/spec/swagger_v2/default_api_spec.rb b/spec/swagger_v2/default_api_spec.rb
index 6c659525..faf4a5b1 100644
--- a/spec/swagger_v2/default_api_spec.rb
+++ b/spec/swagger_v2/default_api_spec.rb
@@ -22,7 +22,7 @@ def app
it 'documents api' do
expect(subject).to eq(
{
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/json"],
"host"=>"example.org",
@@ -66,7 +66,7 @@ def app
it 'documents endpoint' do
expect(subject).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/json"],
"host"=>"example.org",
diff --git a/spec/swagger_v2/hide_api_spec.rb b/spec/swagger_v2/hide_api_spec.rb
index a4475a12..a6122971 100644
--- a/spec/swagger_v2/hide_api_spec.rb
+++ b/spec/swagger_v2/hide_api_spec.rb
@@ -36,7 +36,7 @@ def app
it "retrieves swagger-documentation that doesn't include hidden endpoints" do
expect(subject).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",
@@ -92,7 +92,7 @@ def app
it 'retrieves swagger-documentation on /swagger_doc' do
get '/swagger_doc.json'
expect(JSON.parse(last_response.body)).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",
@@ -110,7 +110,7 @@ def app
it "retrieves the documentation for mounted-api that doesn't include hidden endpoints" do
get '/swagger_doc/simple.json'
expect(JSON.parse(last_response.body)).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",
diff --git a/spec/swagger_v2/mounted_target_class_spec.rb b/spec/swagger_v2/mounted_target_class_spec.rb
index fe8296bd..e64308b2 100644
--- a/spec/swagger_v2/mounted_target_class_spec.rb
+++ b/spec/swagger_v2/mounted_target_class_spec.rb
@@ -29,7 +29,7 @@ def app
it 'retrieves docs for actual api class' do
get '/swagger_doc.json'
expect(JSON.parse(last_response.body)).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",
@@ -51,7 +51,7 @@ def app
it 'retrieves docs for endpoint in actual api class' do
get '/swagger_doc/simple.json'
expect(JSON.parse(last_response.body)).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"tags" => [{"name"=>"simple", "description"=>"Operations about simples"}],
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
diff --git a/spec/swagger_v2/simple_mounted_api_spec.rb b/spec/swagger_v2/simple_mounted_api_spec.rb
index cb2a7ddd..3954f85b 100644
--- a/spec/swagger_v2/simple_mounted_api_spec.rb
+++ b/spec/swagger_v2/simple_mounted_api_spec.rb
@@ -74,7 +74,7 @@ def app
specify do
expect(subject).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",
@@ -149,7 +149,7 @@ def app
specify do
expect(subject).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",
@@ -175,7 +175,7 @@ def app
specify do
expect(subject).to eq({
- "info"=>{"title"=>"API title", "version"=>"v1"},
+ "info"=>{"title"=>"API title", "version"=>"0.0.1"},
"swagger"=>"2.0",
"produces"=>["application/xml", "application/json", "application/octet-stream", "text/plain"],
"host"=>"example.org",