makes version settings more clear (#489)

- updates UPGRADES.md
- adds CHANGELOG entry

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 #### Fixes
 
+* [#489](https://github.com/ruby-grape/grape-swagger/pull/489): Makes version settings/usage more clear; updates `UPGRADE.md`, `README.md` - [@LeFnord](https://github.com/LeFnord).
 * [#476](https://github.com/ruby-grape/grape-swagger/pull/476): Fixes for handling the parameter type when body parameters are defined inside desc block - [@anakinj](https://github.com/anakinj).
 * [#478](https://github.com/ruby-grape/grape-swagger/pull/478): Refactors building of properties, corrects documentation of array items - [@LeFnord](https://github.com/LeFnord).
 * [#479](https://github.com/ruby-grape/grape-swagger/pull/479): Fix regex for Array and Multi Type in doc_methods. Parsing of "[APoint]" should return "APoint" - [@frodrigo](https://github.com/frodrigo).

README.md

@@ -199,8 +199,7 @@ end
 
 
 You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
-
-*not all configuration options supported yet*, but is WIP
+The examples shows the default value.
 
 
 The `host` and `base_path` options also accept a `proc` or `lambda` to evaluate, which is passed a [request](http://www.rubydoc.info/github/rack/rack/Rack/Request) object:
@@ -223,7 +222,7 @@ add_swagger_documentation \
 Base path of the API that's being exposed, default would be taken from `request`.
 ```ruby
 add_swagger_documentation \
-   base_path: '/super/api'
+   base_path: nil
 ```
 
 `host` and `base_path` are also accepting a `proc` or `lambda`
@@ -233,14 +232,14 @@ add_swagger_documentation \
 The path where the API documentation is loaded, default is: `/swagger_doc`.
 ```ruby
 add_swagger_documentation \
-   mount_path: '/docu'
+   mount_path: '/swagger_doc'
 ```
 
 #### add_base_path:
 Add `basePath` key to the documented path keys, default is: `false`.
 ```ruby
 add_swagger_documentation \
-   add_base_path: true
+   add_base_path: true # only if base_path given
 ```
 
 #### add_version:
@@ -249,7 +248,7 @@ here the version is the API version, specified by `grape` in [`path`](https://gi
 
 ```ruby
 add_swagger_documentation \
-   add_version: false
+   add_version: true
 ```
 
 <a name="doc_version" />
@@ -289,9 +288,6 @@ add_swagger_documentation \
   }
 ```
 
-#### *authorizations*:
-This value is added to the `authorizations` key in the JSON documentation.
-
 <a name="models" />
 #### models:
 A list of entities to document. Combine with the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
@@ -333,6 +329,8 @@ add_swagger_documentation \
 
 A hash merged into the `info` key of the JSON documentation.
 
+<!-- #### *authorizations*:
+This value is added to the `authorizations` key in the JSON documentation. -->
 
 <!-- #### *api_documentation*:
 Customize the Swagger API documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description".

UPGRADING.md

@@ -10,6 +10,22 @@ gem 'grape-swagger'
 gem 'grape-swagger-entity'
 ```
 
+`add_swagger_documentation` has changed from
+``` ruby
+  add_swagger_documentation \
+    api_version: '0.0.1'
+```
+to
+
+``` ruby
+  add_swagger_documentation \
+    doc_version: '0.0.1'
+```
+
+The API version self, would be set by grape, see -> [spec for #403](https://github.com/ruby-grape/grape-swagger/blob/master/spec/issues/403_versions_spec.rb).
+
+
+
 ### Upgrading to >= 0.10.2
 
 With grape >= 0.12.0, support for `notes` is replaced by passing a block `detail` option specified. For future compatibility, update your code:

spec/issues/403_versions_spec.rb

@@ -16,31 +16,12 @@ describe 'describing versions' do
 
     subject do
       get '/swagger_doc'
-      JSON.parse(last_response.body, symbolize_names: true)
+      JSON.parse(last_response.body)
     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: {
-              summary: 'no versions given',
-              description: 'no versions given',
-              produces: ['application/json'],
-              responses: {
-                :'200' => { description: 'no versions given' }
-              },
-              tags: ['nothings'],
-              operationId: 'getNothings'
-            }
-          }
-        }
-      )
+      expect(subject['info']['version']).to eql '0.0.1'
+      expect(subject['paths'].keys.first).to eql '/nothings'
     end
   end
 
@@ -59,31 +40,12 @@ describe 'describing versions' do
 
     subject do
       get '/v2/swagger_doc'
-      JSON.parse(last_response.body, symbolize_names: true)
+      JSON.parse(last_response.body)
     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: {
-              summary: 'api versions given',
-              description: 'api versions given',
-              produces: ['application/json'],
-              responses: {
-                :'200' => { description: 'api versions given' }
-              },
-              tags: ['api_version'],
-              operationId: 'getV2ApiVersion'
-            }
-          }
-        }
-      )
+      expect(subject['info']['version']).to eql '0.0.1'
+      expect(subject['paths'].keys.first).to eql '/v2/api_version'
     end
   end
 
@@ -95,80 +57,67 @@ describe 'describing versions' do
           { message: 'hello world …' }
         end
 
-        add_swagger_documentation doc_version: '0.0.2'
+        add_swagger_documentation doc_version: '0.1'
       end
     end
 
     subject do
       get '/swagger_doc'
-      JSON.parse(last_response.body, symbolize_names: true)
+      JSON.parse(last_response.body)
     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: {
-              summary: 'doc versions given',
-              description: 'doc versions given',
-              produces: ['application/json'],
-              responses: {
-                :'200' => { description: 'doc versions given' }
-              },
-              tags: ['doc_version'],
-              operationId: 'getDocVersion'
-            }
-          }
-        }
-      )
+      expect(subject['info']['version']).to eql '0.1'
+      expect(subject['paths'].keys.first).to eql '/doc_version'
     end
   end
 
   describe 'both versions given' do
     def app
       Class.new(Grape::API) do
-        version :v2, using: :path
+        version :v3, using: :path
         desc 'both versions given'
         get '/both_versions' do
           { message: 'hello world …' }
         end
 
-        add_swagger_documentation doc_version: '0.0.2'
+        add_swagger_documentation doc_version: '0.2'
       end
     end
 
     subject do
-      get '/v2/swagger_doc'
-      JSON.parse(last_response.body, symbolize_names: true)
+      get '/v3/swagger_doc'
+      JSON.parse(last_response.body)
     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: {
-              summary: 'both versions given',
-              description: 'both versions given',
-              produces: ['application/json'],
-              responses: {
-                :'200' => { description: 'both versions given' }
-              },
-              tags: ['both_versions'],
-              operationId: 'getV2BothVersions'
-            }
-          }
-        }
-      )
+      expect(subject['info']['version']).to eql '0.2'
+      expect(subject['paths'].keys.first).to eql '/v3/both_versions'
+    end
+  end
+
+  describe 'try to override grape given version' do
+    def app
+      Class.new(Grape::API) do
+        version :v4, using: :path
+        desc 'overriding grape given version?'
+        get '/grape_version' do
+          { message: 'hello world …' }
+        end
+
+        add_swagger_documentation doc_version: '0.0.3',
+                                  version: 'v5'
+      end
+    end
+
+    subject do
+      get '/v4/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['info']['version']).to eql '0.0.3'
+      expect(subject['paths'].keys.first).to eql '/v4/grape_version'
     end
   end
 end