gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/api_swagger_v2_headers_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'headers' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class HeadersApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             headers: {
+               'X-Rate-Limit-Limit' => {
+                 'description' => 'The number of allowed requests in the current period',
+                 'type' => 'integer'
+               }
+             },
+
+             entity: Entities::UseResponse
+        params do
+          optional :param_x, type: String, desc: 'This is a parameter', documentation: { param_type: 'query' }
+        end
+        get '/use_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::HeadersApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    parameters = subject['paths']['/use_headers']['get']['parameters']
+    expect(parameters).to include(
+      'in' => 'header',
+      'name' => 'X-Rate-Limit-Limit',
+      'description' => 'The number of allowed requests in the current period',
+      'type' => 'integer',
+      'format' => 'int32',
+      'required' => false
+    )
+    expect(parameters.size).to eq(2)
+    expect(parameters.first['in']).to eq('header')
+    expect(parameters.last['in']).to eq('query')
+  end
+end

data/spec/swagger_v2/api_swagger_v2_hide_documentation_path_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'hide documentation path' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class HideDocumentationApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+             params: Entities::UseResponse.documentation,
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        params do
+          requires :foo, type: Integer
+        end
+        get '/params_response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+             entity: Entities::UseResponse,
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/entity_response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/present_response' do
+          foo = OpenStruct.new id: 1, name: 'bar'
+          something = OpenStruct.new description: 'something', item: foo
+          present :somethings, something, with: Entities::UseResponse
+        end
+
+        add_swagger_documentation hide_documentation_path: false
+      end
+    end
+  end
+
+  def app
+    TheApi::HideDocumentationApi
+  end
+
+  describe 'shows documentation paths' do
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths'].keys).to include '/swagger_doc', '/swagger_doc/{name}'
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_hide_param_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'hidden flag enables a single endpoint parameter to be excluded from the documentation' do
+  include_context "#{MODEL_PARSER} swagger example"
+  before :all do
+    module TheApi
+      class HideParamsApi < Grape::API
+        helpers do
+          def resource_owner
+            '123'
+          end
+        end
+
+        namespace :flat_params_endpoint do
+          desc 'This is a endpoint with a flat parameter hierarchy' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            requires :name, type: String, documentation: { desc: 'name' }
+            optional :favourite_color, type: String, documentation: { desc: 'I should not be anywhere', hidden: true }
+            optional :proc_param, type: String, documentation: { desc: 'I should not be anywhere', hidden: proc { true } }
+            optional :proc_with_token, type: String, documentation: { desc: 'I may be somewhere', hidden: proc { false } }
+          end
+
+          post do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        namespace :nested_params_endpoint do
+          desc 'This is a endpoint with a nested parameter hierarchy' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            optional :name, type: String, documentation: { desc: 'name' }
+            optional :hidden_attribute, type: Hash do
+              optional :favourite_color, type: String, documentation: { desc: 'I should not be anywhere', hidden: true }
+            end
+
+            optional :attributes, type: Hash do
+              optional :attribute_1, type: String, documentation: { desc: 'Attribute one' }
+              optional :hidden_attribute, type: String, documentation: { desc: 'I should not be anywhere', hidden: true }
+            end
+          end
+
+          post do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        namespace :required_param_endpoint do
+          desc 'This endpoint has hidden defined for a required parameter' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            requires :name, type: String, documentation: { desc: 'name', hidden: true }
+          end
+
+          post do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        add_swagger_documentation token_owner: 'resource_owner'
+      end
+    end
+  end
+
+  let(:app) { TheApi::HideParamsApi }
+
+  describe 'simple flat parameter hierarchy' do
+    subject do
+      get '/swagger_doc/flat_params_endpoint'
+      JSON.parse(last_response.body)
+    end
+
+    it 'ignores parameters that are explicitly hidden' do
+      expect(subject['paths']['/flat_params_endpoint']['post']['parameters'].map { |p| p['name'] }).not_to include('favourite_color', 'proc_param')
+    end
+
+    it 'allows procs to consult the token_owner' do
+      expect(subject['paths']['/flat_params_endpoint']['post']['parameters'].map { |p| p['name'] }).to include('proc_with_token')
+    end
+  end
+
+  describe 'nested parameter hierarchy' do
+    subject do
+      get '/swagger_doc/nested_params_endpoint'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/nested_params_endpoint']['post']['parameters'].map { |p| p['name'] }).not_to include(/hidden_attribute/)
+    end
+  end
+
+  describe 'hidden defined for required parameter' do
+    subject do
+      get '/swagger_doc/required_param_endpoint'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/required_param_endpoint']['post']['parameters'].map { |p| p['name'] }).to include('name')
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_ignore_defaults_spec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'swagger spec v2.0' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'This creates Thing after a delay',
+           success: { code: 202, message: 'OK', model: Entities::Something }
+      params do
+        requires :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
+        requires :links, type: Array, documentation: { type: 'link', is_array: true }
+      end
+      post '/delay_thing' do
+        status 202
+      end
+
+      version 'v3', using: :path
+      add_swagger_documentation api_version: 'v1',
+                                base_path: '/api',
+                                info: {
+                                  title: 'The API title to be displayed on the API homepage.',
+                                  description: 'A description of the API.',
+                                  contact_name: 'Contact name',
+                                  contact_email: 'Contact@email.com',
+                                  contact_url: 'Contact URL',
+                                  license: 'The name of the license.',
+                                  license_url: 'www.The-URL-of-the-license.org',
+                                  terms_of_service_url: 'www.The-URL-of-the-terms-and-service.com'
+                                }
+    end
+  end
+
+  before do
+    get '/v3/swagger_doc'
+  end
+
+  let(:json) { JSON.parse(last_response.body) }
+
+  it 'only returns one response if ignore_defaults is specified' do
+    expect(json['paths']['/delay_thing']['post']['responses']).to eq('202' => { 'description' => 'OK', 'schema' => { '$ref' => '#/definitions/Something' } })
+    expect(json['paths']['/delay_thing']['post']['responses'].keys).not_to include '201'
+  end
+end

data/spec/swagger_v2/api_swagger_v2_mounted_spec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'swagger spec v2.0' do
+  describe 'mounted APIs' do
+    include_context "#{MODEL_PARSER} swagger example"
+
+    def app
+      Class.new(Grape::API) do
+        format :json
+
+        #  Thing stuff
+        desc 'This gets Things.' do
+          consumes ['application/x-www-form-urlencoded']
+          params Entities::Something.documentation
+          http_codes [{ code: 401, message: 'Unauthorized', model: Entities::ApiError }]
+        end
+        get '/thing' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This gets Things.' do
+          consumes ['application/x-www-form-urlencoded']
+          http_codes [
+            { code: 200, message: 'get Horses', model: Entities::Something },
+            { code: 401, message: 'HorsesOutError', model: Entities::ApiError }
+          ]
+        end
+        get '/thing2' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This gets Thing.' do
+          consumes ['application/x-www-form-urlencoded']
+          http_codes [{ code: 200, message: 'getting a single thing' }, { code: 401, message: 'Unauthorized' }]
+        end
+        params do
+          requires :id, type: Integer
+        end
+        get '/thing/:id' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This creates Thing.',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::Something
+        params do
+          requires :text, type: String, documentation: { type: 'string', desc: 'Content of something.' }
+          requires :links, type: Array, documentation: { type: 'link', is_array: true }
+        end
+        post '/thing', http_codes: [{ code: 422, message: 'Unprocessible Entity' }] do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This updates Thing.',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::Something
+        params do
+          requires :id, type: Integer
+          optional :text, type: String, desc: 'Content of something.'
+          optional :links, type: Array, documentation: { type: 'link', is_array: true }
+        end
+        put '/thing/:id' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'This deletes Thing.',
+          consumes: ['application/x-www-form-urlencoded'],
+          entity: Entities::Something
+        params do
+          requires :id, type: Integer
+        end
+        delete '/thing/:id' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Entities::Something
+        end
+
+        desc 'dummy route.',
+          consumes: ['application/x-www-form-urlencoded'],
+          failure: [{ code: 401, message: 'Unauthorized' }]
+        params do
+          requires :id, type: Integer
+        end
+        delete '/dummy/:id' do
+          {}
+        end
+
+        namespace :other_thing do
+          desc 'nested route inside namespace',
+            consumes: ['application/x-www-form-urlencoded'],
+            entity: Entities::QueryInput,
+            x: {
+              'amazon-apigateway-auth' => { type: 'none' },
+              'amazon-apigateway-integration' => { type: 'aws', uri: 'foo_bar_uri', httpMethod: 'get' }
+            }
+
+          params do
+            requires :elements, documentation: {
+              type: 'QueryInputElement',
+              desc: 'Set of configuration',
+              param_type: 'body',
+              is_array: true,
+              required: true
+            }
+          end
+          get '/:elements' do
+            present something, with: Entities::QueryInput
+          end
+        end
+
+        version 'v3', using: :path
+        add_swagger_documentation base_path: '/api',
+                                  info: {
+                                    title: 'The API title to be displayed on the API homepage.',
+                                    description: 'A description of the API.',
+                                    contact_name: 'Contact name',
+                                    contact_email: 'Contact@email.com',
+                                    contact_url: 'Contact URL',
+                                    license: 'The name of the license.',
+                                    license_url: 'www.The-URL-of-the-license.org',
+                                    terms_of_service_url: 'www.The-URL-of-the-terms-and-service.com'
+                                  }
+      end
+    end
+
+    mounted_paths.each do |expected_path|
+      describe "documents only #{expected_path} paths" do
+        let(:mount_path) { "/v3/swagger_doc#{expected_path}" }
+        subject do
+          get mount_path
+          JSON.parse(last_response.body)['paths']
+        end
+
+        specify do
+          unexpected_paths = mounted_paths - [expected_path]
+          subject.each_key do |path|
+            unexpected_paths.each do |unexpected_path|
+              expect(path).not_to start_with unexpected_path
+            end
+            expect(path).to start_with(expected_path).or include(expected_path)
+            expect(subject[path]).to eql swagger_json['paths'][path]
+          end
+        end
+      end
+    end
+  end
+end