gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/api_swagger_v2_additional_properties_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'parsing additional_parameters' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :things do
+        class Element < Grape::Entity
+          expose :id
+        end
+
+        params do
+          optional :closed, type: Hash, documentation: { additional_properties: false, in: 'body' } do
+            requires :only
+          end
+          optional :open, type: Hash, documentation: { additional_properties: true }
+          optional :type_limited, type: Hash, documentation: { additional_properties: String }
+          optional :ref_limited, type: Hash, documentation: { additional_properties: Element }
+          optional :fallback, type: Hash, documentation: { additional_properties: { type: 'integer' } }
+        end
+        post do
+          present params
+        end
+      end
+
+      add_swagger_documentation format: :json, models: [Element]
+    end
+  end
+
+  subject do
+    get '/swagger_doc/things'
+    JSON.parse(last_response.body)
+  end
+
+  describe 'POST' do
+    specify do
+      expect(subject.dig('paths', '/things', 'post', 'parameters')).to eql(
+        [
+          { 'name' => 'postThings', 'in' => 'body', 'required' => true, 'schema' => { '$ref' => '#/definitions/postThings' } }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject.dig('definitions', 'postThings')).to eql(
+        'type' => 'object',
+        'properties' => {
+          'closed' => {
+            'type' => 'object',
+            'additionalProperties' => false,
+            'properties' => {
+              'only' => { 'type' => 'string' }
+            },
+            'required' => ['only']
+          },
+          'open' => {
+            'type' => 'object',
+            'additionalProperties' => true
+          },
+          'type_limited' => {
+            'type' => 'object',
+            'additionalProperties' => {
+              'type' => 'string'
+            }
+          },
+          'ref_limited' => {
+            'type' => 'object',
+            'additionalProperties' => {
+              '$ref' => '#/definitions/Element'
+            }
+          },
+          'fallback' => {
+            'type' => 'object',
+            'additionalProperties' => {
+              'type' => 'integer'
+            }
+          }
+        }
+      )
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_body_definitions_spec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'body parameter definitions' do
+  before :all do
+    module TheBodyApi
+      class Endpoint < Grape::API
+        resource :endpoint do
+          desc 'The endpoint' do
+            headers XAuthToken: {
+              description: 'Valdates your identity',
+              required: true
+            }
+            params body_param: { type: 'String', desc: 'param', documentation: { in: 'body' } },
+                   body_type_as_const_param: { type: String, desc: 'string_param', documentation: { in: 'body' } }
+          end
+
+          post do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheBodyApi::Endpoint
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  context 'a definition is generated for the endpoints parameters defined within the desc block' do
+    specify do
+      expect(subject['definitions']['postEndpoint']['properties']).to eql(
+        'body_param' => { 'type' => 'string', 'description' => 'param' },
+        'body_type_as_const_param' => { 'type' => 'string', 'description' => 'string_param' }
+      )
+
+      expect(subject['paths']['/endpoint']['post']['parameters'].any? { |p| p['name'] == 'XAuthToken' && p['in'] == 'header' }).to eql(true)
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_definitions-models_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'definitions/models' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ModelApi < Grape::API
+        format :json
+
+        add_swagger_documentation models: [
+          ::Entities::UseResponse,
+          ::Entities::ApiError,
+          ::Entities::RecursiveModel,
+          ::Entities::DocumentedHashAndArrayModel
+        ]
+      end
+    end
+  end
+
+  def app
+    TheApi::ModelApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject).to include 'definitions'
+    expect(subject['definitions']).to include(swagger_definitions_models)
+  end
+end

data/spec/swagger_v2/api_swagger_v2_detail_spec.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+def details
+  <<-DETAILS
+    # Burgers in Heaven
+
+    > A burger doesn't come for free
+
+    If you want to reserve a burger in heaven, you have to do
+    some crazy stuff on earth.
+
+    ```
+    def do_good
+    puts 'help people'
+    end
+    ```
+
+    * _Will go to Heaven:_ Probably
+    * _Will go to Hell:_ Probably not
+  DETAILS
+end
+
+describe 'details' do
+  describe 'take deatils as it is' do
+    include_context "#{MODEL_PARSER} swagger example"
+
+    before :all do
+      module TheApi
+        class DetailApi < Grape::API
+          format :json
+
+          desc 'This returns something',
+               detail: 'detailed description of the route',
+               entity: Entities::UseResponse,
+               failure: [{ code: 400, model: Entities::ApiError }]
+          get '/use_detail' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'This returns something' do
+            detail 'detailed description of the route inside the `desc` block'
+            entity Entities::UseResponse
+            failure [{ code: 400, model: Entities::ApiError }]
+          end
+          get '/use_detail_block' do
+            { 'declared_params' => declared(params) }
+          end
+
+          add_swagger_documentation
+        end
+      end
+    end
+
+    def app
+      TheApi::DetailApi
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_detail']['get']).to include('summary')
+      expect(subject['paths']['/use_detail']['get']['summary']).to eql 'This returns something'
+      expect(subject['paths']['/use_detail']['get']).to include('description')
+      expect(subject['paths']['/use_detail']['get']['description']).to eql 'detailed description of the route'
+    end
+
+    specify do
+      expect(subject['paths']['/use_detail_block']['get']).to include('summary')
+      expect(subject['paths']['/use_detail_block']['get']['summary']).to eql 'This returns something'
+      expect(subject['paths']['/use_detail_block']['get']).to include('description')
+      expect(subject['paths']['/use_detail_block']['get']['description']).to eql 'detailed description of the route inside the `desc` block'
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_extensions_spec.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'extensions' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ExtensionsApi < Grape::API
+        format :json
+
+        route_setting :x_path, some: 'stuff'
+
+        desc 'This returns something with extension on path level',
+             params: Entities::UseResponse.documentation,
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/path_extension' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :x_operation, some: 'stuff'
+
+        desc 'This returns something with extension on verb level',
+             params: Entities::UseResponse.documentation,
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        params do
+          requires :id, type: Integer
+        end
+        get '/verb_extension' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :x_def, for: 200, some: 'stuff'
+
+        desc 'This returns something with extension on definition level',
+             params: Entities::ResponseItem.documentation,
+             success: Entities::ResponseItem,
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/definitions_extension' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }]
+
+        desc 'This returns something with extension on definition level',
+             success: Entities::OtherItem
+        get '/non_existend_status_definitions_extension' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :x_def, [{ for: 422, other: 'stuff' }, { for: 200, some: 'stuff' }]
+
+        desc 'This returns something with extension on definition level',
+             success: Entities::OtherItem,
+             failure: [{ code: 422, message: 'NotFound', model: Entities::SecondApiError }]
+        get '/multiple_definitions_extension' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation(x: { some: 'stuff' })
+      end
+    end
+  end
+
+  def app
+    TheApi::ExtensionsApi
+  end
+
+  describe 'extension on root level' do
+    subject do
+      get '/swagger_doc/path_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to include 'x-some'
+      expect(subject['x-some']).to eql 'stuff'
+    end
+  end
+
+  describe 'extension on path level' do
+    subject do
+      get '/swagger_doc/path_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/path_extension']).to include 'x-some'
+      expect(subject['paths']['/path_extension']['x-some']).to eql 'stuff'
+    end
+  end
+
+  describe 'extension on verb level' do
+    subject do
+      get '/swagger_doc/verb_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/verb_extension']['get']).to include 'x-some'
+      expect(subject['paths']['/verb_extension']['get']['x-some']).to eql 'stuff'
+    end
+  end
+
+  describe 'extension on definition level' do
+    subject do
+      get '/swagger_doc/definitions_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['definitions']['ResponseItem']).to include 'x-some'
+      expect(subject['definitions']['ResponseItem']['x-some']).to eql 'stuff'
+      expect(subject['definitions']['ApiError']).not_to include 'x-some'
+    end
+  end
+
+  describe 'extension on definition level' do
+    subject do
+      get '/swagger_doc/multiple_definitions_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['definitions']['OtherItem']).to include 'x-some'
+      expect(subject['definitions']['OtherItem']['x-some']).to eql 'stuff'
+      expect(subject['definitions']['SecondApiError']).to include 'x-other'
+      expect(subject['definitions']['SecondApiError']['x-other']).to eql 'stuff'
+    end
+  end
+
+  describe 'extension on definition level' do
+    subject do
+      get '/swagger_doc/non_existend_status_definitions_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['definitions'].length).to eql 1
+      expect(subject['definitions']['OtherItem']).to include 'x-some'
+      expect(subject['definitions']['OtherItem']['x-some']).to eql 'stuff'
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_format-content_type_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'format, content_type' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ProducesApi < Grape::API
+        format :json
+
+        desc 'This uses json (default) for produces',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             entity: Entities::UseResponse
+        get '/use_default' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This uses formats for produces',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             formats: [:xml, :binary, 'application/vdns'],
+             entity: Entities::UseResponse
+        get '/use_formats' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This uses content_types for produces',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             content_types: [:xml, :binary, 'application/vdns'],
+             entity: Entities::UseResponse
+        get '/use_content_types' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This uses produces for produces',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             produces: [:xml, :binary, 'application/vdns'],
+             entity: Entities::UseResponse
+        get '/use_produces' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This uses consumes for consumes',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             consumes: ['application/www_url_encoded'],
+             entity: Entities::UseResponse
+        post '/use_consumes' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This uses consumes for consumes',
+             failure: [{ code: 400, model: Entities::ApiError }],
+             consumes: ['application/www_url_encoded'],
+             entity: Entities::UseResponse
+        patch '/use_consumes' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ProducesApi
+  end
+
+  let(:produced) do
+    [
+      'application/xml',
+      'application/octet-stream',
+      'application/vdns'
+    ]
+  end
+
+  describe 'formats' do
+    subject do
+      get '/swagger_doc/use_default'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_default']['get']).to include('produces')
+      expect(subject['paths']['/use_default']['get']['produces']).to eql(['application/json'])
+    end
+  end
+
+  describe 'formats' do
+    subject do
+      get '/swagger_doc/use_formats'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_formats']['get']).to include('produces')
+      expect(subject['paths']['/use_formats']['get']['produces']).to eql(produced)
+    end
+  end
+
+  describe 'content types' do
+    subject do
+      get '/swagger_doc/use_content_types'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_content_types']['get']).to include('produces')
+      expect(subject['paths']['/use_content_types']['get']['produces']).to eql(produced)
+    end
+  end
+
+  describe 'produces' do
+    subject do
+      get '/swagger_doc/use_produces'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_produces']['get']).to include('produces')
+      expect(subject['paths']['/use_produces']['get']['produces']).to eql(produced)
+    end
+  end
+
+  describe 'consumes' do
+    subject do
+      get '/swagger_doc/use_consumes'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_consumes']['post']).to include('consumes')
+      expect(subject['paths']['/use_consumes']['post']['consumes']).to eql ['application/www_url_encoded']
+      expect(subject['paths']['/use_consumes']['patch']['consumes']).to eql ['application/www_url_encoded']
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_global_configuration_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'global configuration stuff' do
+  before :all do
+    module TheApi
+      class ConfigurationApi < Grape::API
+        format :json
+        version 'v3', using: :path
+
+        desc 'This returns something',
+             failure: [{ code: 400, message: 'NotFound' }]
+        params do
+          requires :foo, type: Integer
+        end
+        get :configuration do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation format: :json,
+                                  doc_version: '23',
+                                  schemes: 'https',
+                                  host: -> { 'another.host.com' },
+                                  base_path: -> { 'somewhere/over/the/rainbow' },
+                                  mount_path: 'documentation',
+                                  add_base_path: true,
+                                  add_version: true,
+                                  security_definitions: { api_key: { foo: 'bar' } },
+                                  security: [{ api_key: [] }]
+      end
+    end
+  end
+
+  def app
+    TheApi::ConfigurationApi
+  end
+
+  describe 'shows documentation paths' do
+    subject do
+      get '/v3/documentation'
+      JSON.parse(last_response.body)
+    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'
+      expect(subject['schemes']).to eql ['https']
+      expect(subject['securityDefinitions'].keys).to include('api_key')
+      expect(subject['securityDefinitions']['api_key']).to include('foo' => 'bar')
+      expect(subject['security']).to include('api_key' => [])
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_hash_and_array_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'document hash and array' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class TestApi < Grape::API
+        format :json
+
+        if ::Entities::DocumentedHashAndArrayModel.respond_to?(:documentation)
+          documentation = ::Entities::DocumentedHashAndArrayModel.documentation
+        end
+
+        desc 'This returns something'
+        namespace :arbitrary do
+          params do
+            requires :id, type: Integer
+          end
+          route_param :id do
+            desc 'Timeless treasure'
+            params do
+              requires :body, using: documentation unless documentation.nil?
+              requires :raw_hash, type: Hash, documentation: { param_type: 'body' } if documentation.nil?
+              requires :raw_array, type: Array, documentation: { param_type: 'body' } if documentation.nil?
+            end
+            put '/id_and_hash' do
+              {}
+            end
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::TestApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+  describe 'generated request definition' do
+    it 'has hash' do
+      expect(subject['definitions'].keys).to include('putArbitraryIdIdAndHash')
+      expect(subject['definitions']['putArbitraryIdIdAndHash']['properties'].keys).to include('raw_hash')
+    end
+
+    it 'has array' do
+      expect(subject['definitions'].keys).to include('putArbitraryIdIdAndHash')
+      expect(subject['definitions']['putArbitraryIdIdAndHash']['properties'].keys).to include('raw_array')
+    end
+
+    it 'does not have the path parameter' do
+      expect(subject['definitions'].keys).to include('putArbitraryIdIdAndHash')
+      expect(subject['definitions']['putArbitraryIdIdAndHash']).to_not include('id')
+    end
+  end
+end