corrects documentation of versions (#405)

.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

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).
 
 

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,42 +139,51 @@ You can pass a hash with optional configuration settings to ```add_swagger_docum
 
 <a name="host" />
 #### 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'
 ```
 
 <a name="base_path" />
 #### 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'
 ```
 
 <a name="mount_path" />
 #### 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
 ```
 
+<a name="doc_version" />
+#### 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'
+```
 
 <a name="markdown" />
 #### markdown:
@@ -190,15 +199,6 @@ add_swagger_documentation \
   markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new
 ```
 
-<a name="api_version" />
-#### 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.

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,

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

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

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

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"],

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'

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",

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",