From 97e00d02153009fa77e83cae6fe4625b749f8830 Mon Sep 17 00:00:00 2001 From: Peter Scholz Date: Sat, 30 Apr 2016 01:47:01 +0200 Subject: [PATCH] corrects documentation of versions --- .travis.yml | 7 +- CHANGELOG.md | 1 + README.md | 35 ++-- lib/grape-swagger/doc_methods.rb | 2 +- lib/grape-swagger/doc_methods/path_string.rb | 2 +- lib/grape-swagger/endpoint.rb | 4 +- spec/issues/403_versions_spec.rb | 157 ++++++++++++++++++ spec/support/api_swagger_v2_result.rb | 2 +- ...pi_swagger_v2_global_configuration_spec.rb | 3 +- .../api_swagger_v2_response_spec.rb | 6 +- spec/swagger_v2/default_api_spec.rb | 4 +- spec/swagger_v2/hide_api_spec.rb | 6 +- spec/swagger_v2/mounted_target_class_spec.rb | 4 +- spec/swagger_v2/simple_mounted_api_spec.rb | 6 +- 14 files changed, 199 insertions(+), 40 deletions(-) create mode 100644 spec/issues/403_versions_spec.rb 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",