gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/params_nested_spec.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'nested group params' do
+  [true, false].each do |array_use_braces|
+    context "when array_use_braces option is set to #{array_use_braces}" do
+      let(:braces) { array_use_braces ? '[]' : '' }
+      let(:app) do
+        Class.new(Grape::API) do
+          format :json
+
+          desc 'nested array' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            requires :a_array, type: Array do
+              requires :param_1, type: Integer
+              requires :b_array, type: Array do
+                requires :param_2, type: String
+              end
+              requires :c_hash, type: Hash do
+                requires :param_3, type: String
+              end
+            end
+            requires :a_array_foo, type: String
+          end
+          post '/nested_array' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'nested hash' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            requires :a_hash, type: Hash do
+              requires :param_1, type: Integer
+              requires :b_hash, type: Hash do
+                requires :param_2, type: String
+              end
+              requires :c_array, type: Array do
+                requires :param_3, type: String
+              end
+            end
+            requires :a_hash_foo, type: String
+          end
+          post '/nested_hash' do
+            { 'declared_params' => declared(params) }
+          end
+
+          add_swagger_documentation array_use_braces: array_use_braces
+        end
+      end
+
+      describe 'retrieves the documentation for nested array parameters' do
+        subject do
+          get '/swagger_doc/nested_array'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['paths']['/nested_array']['post']['parameters']).to eql(
+            [
+              { 'in' => 'formData', 'name' => "a_array#{braces}[param_1]", 'required' => true, 'type' => 'array', 'items' => { 'type' => 'integer', 'format' => 'int32' } },
+              { 'in' => 'formData', 'name' => "a_array#{braces}[b_array]#{braces}[param_2]", 'required' => true, 'type' => 'array', 'items' => { 'type' => 'string' } },
+              { 'in' => 'formData', 'name' => "a_array#{braces}[c_hash][param_3]", 'required' => true, 'type' => 'array', 'items' => { 'type' => 'string' } },
+              { 'in' => 'formData', 'name' => 'a_array_foo', 'required' => true, 'type' => 'string' }
+            ]
+          )
+        end
+      end
+
+      describe 'retrieves the documentation for nested hash parameters' do
+        subject do
+          get '/swagger_doc/nested_hash'
+          JSON.parse(last_response.body)
+        end
+
+        specify do
+          expect(subject['paths']['/nested_hash']['post']['parameters']).to eql(
+            [
+              { 'in' => 'formData', 'name' => 'a_hash[param_1]', 'required' => true, 'type' => 'integer', 'format' => 'int32' },
+              { 'in' => 'formData', 'name' => 'a_hash[b_hash][param_2]', 'required' => true, 'type' => 'string' },
+              { 'in' => 'formData', 'name' => "a_hash[c_array]#{braces}[param_3]", 'required' => true, 'type' => 'array', 'items' => { 'type' => 'string' } },
+              { 'in' => 'formData', 'name' => 'a_hash_foo', 'required' => true, 'type' => 'string' }
+            ]
+          )
+        end
+      end
+    end
+  end
+end

data/spec/swagger_v2/parent_less_namespace_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'a parent less namespace' do
+  include_context 'namespace example'
+
+  before :all do
+    class ParentLessApi < Grape::API
+      prefix :api
+      mount TheApi::ParentLessNamespaceApi
+      add_swagger_documentation version: 'v1'
+    end
+  end
+
+  def app
+    ParentLessApi
+  end
+
+  describe 'retrieves swagger-documentation on /swagger_doc' do
+    let(:route_name) { ':animal/:breed/queues/:queue_id/reservations' }
+    subject do
+      get '/api/swagger_doc.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/api/{animal}/{breed}/queues/{queue_id}/reservations']['get']['operationId'])
+        .to start_with('getApiAnimalBreedQueuesQueueIdReservations')
+    end
+  end
+end

data/spec/swagger_v2/reference_entity_spec.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'referenceEntity' do
+  before :all do
+    module MyAPI
+      module Entities
+        class Something < Grape::Entity
+          def self.entity_name
+            'SomethingCustom'
+          end
+
+          expose :text, documentation: { type: 'string', desc: 'Content of something.' }
+        end
+
+        class Kind < Grape::Entity
+          def self.entity_name
+            'KindCustom'
+          end
+
+          expose :title, documentation: { type: 'string', desc: 'Title of the kind.' }
+          expose :something, documentation: { type: Something, desc: 'Something interesting.' }
+        end
+
+        class Base < Grape::Entity
+          def self.entity_name
+            parts = to_s.split('::')
+
+            "MyAPI::#{parts.last}"
+          end
+
+          expose :title, documentation: { type: 'string', desc: 'Title of the parent.' }
+        end
+
+        class Child < Base
+          expose :child, documentation: { type: 'string', desc: 'Child property.' }
+        end
+      end
+
+      class ResponseModelApi < Grape::API
+        format :json
+        desc 'This returns kind and something or an error',
+             params: Entities::Kind.documentation.slice(:something),
+             entity: Entities::Kind,
+             http_codes: [
+               { code: 200, message: 'OK', model: Entities::Kind }
+             ]
+        params do
+          optional :something, desc: 'something as parameter'
+        end
+        get '/kind' do
+          kind = OpenStruct.new text: 'kind'
+          present kind, with: Entities::Kind
+        end
+
+        desc 'This returns a child entity',
+             entity: Entities::Child,
+             http_codes: [
+               { code: 200, message: 'OK', model: Entities::Child }
+             ]
+        get '/child' do
+          child = OpenStruct.new text: 'child'
+          present child, with: Entities::Child
+        end
+
+        add_swagger_documentation # models: [MyAPI::Entities::Something, MyAPI::Entities::Kind]
+      end
+    end
+  end
+
+  def app
+    MyAPI::ResponseModelApi
+  end
+
+  describe 'kind' do
+    subject do
+      get '/swagger_doc/kind'
+      JSON.parse(last_response.body)
+    end
+
+    it 'should document specified models' do
+      expect(subject['paths']['/kind']['get']['parameters']).to eq [{
+        'in' => 'query',
+        'name' => 'something',
+        'description' => 'Something interesting.',
+        'type' => 'SomethingCustom',
+        'required' => false
+      }]
+
+      expect(subject['definitions'].keys).to include 'SomethingCustom'
+      expect(subject['definitions']['SomethingCustom']).to eq(
+        'type' => 'object', 'properties' => { 'text' => { 'type' => 'string', 'description' => 'Content of something.' } }
+      )
+
+      expect(subject['definitions'].keys).to include 'KindCustom'
+      expect(subject['definitions']['KindCustom']).to eq(
+        'type' => 'object',
+        'properties' => {
+          'title' => { 'type' => 'string', 'description' => 'Title of the kind.' },
+          'something' => {
+            '$ref' => '#/definitions/SomethingCustom',
+            'description' => 'Something interesting.'
+          }
+        },
+        'description' => 'KindCustom model'
+      )
+    end
+  end
+
+  describe 'child' do
+    subject do
+      get '/swagger_doc/child'
+      JSON.parse(last_response.body)
+    end
+
+    it 'should document specified models' do
+      expect(subject['definitions'].keys).to include 'MyAPI::Child'
+      expect(subject['definitions']['MyAPI::Child']).to eq(
+        'type' => 'object',
+        'properties' => {
+          'title' => { 'type' => 'string', 'description' => 'Title of the parent.' },
+          'child' => { 'type' => 'string', 'description' => 'Child property.' }
+        },
+        'description' => 'MyAPI::Child model'
+      )
+    end
+  end
+end

data/spec/swagger_v2/security_requirement_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'security requirement on endpoint method' do
+  def app
+    Class.new(Grape::API) do
+      desc 'Endpoint with security requirement', security: [{ oauth_pets: ['read:pets', 'write:pets'] }]
+      get '/with_security' do
+        { foo: 'bar' }
+      end
+
+      desc 'Endpoint without security requirement', security: []
+      get '/without_security' do
+        { foo: 'bar' }
+      end
+
+      add_swagger_documentation(
+        security_definitions: {
+          petstore_auth: {
+            type: 'oauth2',
+            flow: 'implicit',
+            authorizationUrl: 'https://petstore.swagger.io/oauth/dialog',
+            scopes: {
+              'read:pets': 'read your pets',
+              'write:pets': 'modify pets in your account'
+            }
+          }
+        }
+      )
+    end
+  end
+
+  subject do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body)
+  end
+
+  it 'defines the security requirement on the endpoint method' do
+    expect(subject['paths']['/with_security']['get']['security']).to eql [{ 'oauth_pets' => ['read:pets', 'write:pets'] }]
+  end
+
+  it 'defines an empty security requirement on the endpoint method' do
+    expect(subject['paths']['/without_security']['get']['security']).to eql []
+  end
+end

data/spec/swagger_v2/simple_mounted_api_spec.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'a simple mounted api' do
+  before :all do
+    # rubocop:disable Lint/EmptyClass
+    class CustomType; end
+    # rubocop:enable Lint/EmptyClass
+
+    class SimpleMountedApi < Grape::API
+      desc 'Document root',
+        consumes: ['application/x-www-form-urlencoded']
+      get do
+        { message: 'hi' }
+      end
+
+      desc 'This gets something.',
+        consumes: ['application/x-www-form-urlencoded'],
+        notes: '_test_'
+
+      get '/simple' do
+        { bla: 'something' }
+      end
+
+      desc 'This gets something for URL using - separator.',
+        consumes: ['application/x-www-form-urlencoded'],
+        notes: '_test_'
+
+      get '/simple-test' do
+        { bla: 'something' }
+      end
+
+      head '/simple-head-test' do
+        status 200
+      end
+
+      options '/simple-options-test' do
+        status 200
+      end
+
+      desc 'this gets something else',
+        consumes: ['application/x-www-form-urlencoded'],
+        headers: {
+          'XAuthToken' => { description: 'A required header.', required: true },
+          'XOtherHeader' => { description: 'An optional header.', required: false }
+        },
+        http_codes: [
+          { code: 403, message: 'invalid pony' },
+          { code: 405, message: 'no ponies left!' }
+        ]
+
+      get '/simple_with_headers' do
+        { bla: 'something_else' }
+      end
+
+      desc 'this takes an array of parameters',
+        consumes: ['application/x-www-form-urlencoded'],
+        params: {
+          'items[]' => { description: 'array of items', is_array: true }
+        }
+
+      post '/items' do
+        {}
+      end
+
+      desc 'this uses a custom parameter',
+        consumes: ['application/x-www-form-urlencoded'],
+        params: {
+          'custom' => { type: CustomType, description: 'array of items', is_array: true }
+        }
+
+      get '/custom' do
+        {}
+      end
+    end
+
+    class SimpleApi < Grape::API
+      mount SimpleMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    SimpleApi
+  end
+
+  describe 'retrieves swagger-documentation on /swagger_doc' do
+    subject do
+      get '/swagger_doc.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to eq(
+        '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' => 'simple', 'description' => 'Operations about simples' },
+          { 'name' => 'simple-test', 'description' => 'Operations about simple-tests' },
+          { 'name' => 'simple-head-test', 'description' => 'Operations about simple-head-tests' },
+          { 'name' => 'simple-options-test', 'description' => 'Operations about simple-options-tests' },
+          { 'name' => 'simple_with_headers', 'description' => 'Operations about simple_with_headers' },
+          { 'name' => 'items', 'description' => 'Operations about items' },
+          { 'name' => 'custom', 'description' => 'Operations about customs' }
+        ],
+        'paths' => {
+          '/' => {
+            'get' => {
+              'description' => 'Document root',
+              'produces' => ['application/json'],
+              'responses' => { '200' => { 'description' => 'Document root' } },
+              'operationId' => 'get'
+            }
+          },
+          '/simple' => {
+            'get' => {
+              'description' => 'This gets something.',
+              'produces' => ['application/json'],
+              'tags' => ['simple'],
+              'operationId' => 'getSimple',
+              'responses' => { '200' => { 'description' => 'This gets something.' } }
+            }
+          },
+          '/simple-test' => {
+            'get' => {
+              'description' => 'This gets something for URL using - separator.',
+              'produces' => ['application/json'],
+              'tags' => ['simple-test'],
+              'operationId' => 'getSimpleTest',
+              'responses' => { '200' => { 'description' => 'This gets something for URL using - separator.' } }
+            }
+          },
+          '/simple-head-test' => {
+            'head' => {
+              'produces' => ['application/json'],
+              'responses' => { '200' => { 'description' => 'head SimpleHeadTest' } },
+              'tags' => ['simple-head-test'],
+              'operationId' => 'headSimpleHeadTest'
+            }
+          },
+          '/simple-options-test' => {
+            'options' => {
+              'produces' => ['application/json'],
+              'responses' => { '200' => { 'description' => 'option SimpleOptionsTest' } },
+              'tags' => ['simple-options-test'],
+              'operationId' => 'optionsSimpleOptionsTest'
+            }
+          },
+          '/simple_with_headers' => {
+            'get' => {
+              'description' => 'this gets something else',
+              'produces' => ['application/json'],
+              'parameters' => [
+                { 'in' => 'header', 'name' => 'XAuthToken', 'description' => 'A required header.', 'type' => 'string', 'required' => true },
+                { 'in' => 'header', 'name' => 'XOtherHeader', 'description' => 'An optional header.', 'type' => 'string', 'required' => false }
+              ],
+              'tags' => ['simple_with_headers'],
+              'operationId' => 'getSimpleWithHeaders',
+              'responses' => {
+                '200' => { 'description' => 'this gets something else' },
+                '403' => { 'description' => 'invalid pony' },
+                '405' => { 'description' => 'no ponies left!' }
+              }
+            }
+          },
+          '/items' => {
+            'post' => {
+              'description' => 'this takes an array of parameters',
+              'produces' => ['application/json'],
+              'consumes' => ['application/x-www-form-urlencoded'],
+              'parameters' => [{ 'in' => 'formData', 'name' => 'items[]', 'description' => 'array of items', 'required' => false, 'type' => 'array', 'items' => { 'type' => 'string' } }],
+              'tags' => ['items'],
+              'operationId' => 'postItems',
+              'responses' => { '201' => { 'description' => 'this takes an array of parameters' } }
+            }
+          },
+          '/custom' => {
+            'get' => {
+              'description' => 'this uses a custom parameter',
+              'produces' => ['application/json'],
+              'parameters' => [{ 'in' => 'formData', 'name' => 'custom', 'description' => 'array of items', 'required' => false, 'type' => 'array', 'items' => { 'type' => 'CustomType' } }],
+              'tags' => ['custom'],
+              'operationId' => 'getCustom',
+              'responses' => { '200' => { 'description' => 'this uses a custom parameter' } }
+            }
+          }
+        }
+      )
+    end
+  end
+
+  describe 'retrieves the documentation for mounted-api' do
+    subject do
+      get '/swagger_doc/simple.json'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to eq(
+        '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' => 'simple', 'description' => 'Operations about simples' }
+        ],
+        'paths' => {
+          '/simple' => {
+            'get' => {
+              'description' => 'This gets something.',
+              'produces' => ['application/json'],
+              'tags' => ['simple'],
+              'operationId' => 'getSimple',
+              'responses' => { '200' => { 'description' => 'This gets something.' } }
+            }
+          }
+        }
+      )
+    end
+  end
+
+  describe 'retrieves the documentation for mounted-api that' do
+    describe "contains '-' in URL" do
+      subject do
+        get '/swagger_doc/simple-test.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject).to eq(
+          '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' => 'simple-test', 'description' => 'Operations about simple-tests' }
+          ],
+          'paths' => {
+            '/simple-test' => {
+              'get' => {
+                'description' => 'This gets something for URL using - separator.',
+                'produces' => ['application/json'],
+                'tags' => ['simple-test'],
+                'operationId' => 'getSimpleTest',
+                'responses' => { '200' => { 'description' => 'This gets something for URL using - separator.' } }
+              }
+            }
+          }
+        )
+      end
+    end
+
+    describe 'includes headers' do
+      subject do
+        get '/swagger_doc/simple_with_headers.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']).to eq(
+          '/simple_with_headers' => {
+            'get' => {
+              'description' => 'this gets something else',
+              'produces' => ['application/json'],
+              'parameters' => [
+                { 'in' => 'header', 'name' => 'XAuthToken', 'description' => 'A required header.', 'type' => 'string', 'required' => true },
+                { 'in' => 'header', 'name' => 'XOtherHeader', 'description' => 'An optional header.', 'type' => 'string', 'required' => false }
+              ],
+              'tags' => ['simple_with_headers'],
+              'operationId' => 'getSimpleWithHeaders',
+              'responses' => {
+                '200' => { 'description' => 'this gets something else' },
+                '403' => { 'description' => 'invalid pony' },
+                '405' => { 'description' => 'no ponies left!' }
+              }
+            }
+          }
+        )
+      end
+    end
+
+    describe 'supports array params' do
+      subject do
+        get '/swagger_doc/items.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']).to eq(
+          '/items' => {
+            'post' => {
+              'description' => 'this takes an array of parameters',
+              'produces' => ['application/json'],
+              'consumes' => ['application/x-www-form-urlencoded'],
+              'parameters' => [{ 'in' => 'formData', 'name' => 'items[]', 'description' => 'array of items', 'required' => false, 'type' => 'array', 'items' => { 'type' => 'string' } }],
+              'tags' => ['items'],
+              'operationId' => 'postItems',
+              'responses' => { '201' => { 'description' => 'this takes an array of parameters' } }
+            }
+          }
+        )
+      end
+    end
+
+    describe 'supports custom params types' do
+      subject do
+        get '/swagger_doc/custom.json'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']).to eq(
+          '/custom' => {
+            'get' => {
+              'description' => 'this uses a custom parameter',
+              'produces' => ['application/json'],
+              'parameters' => [{ 'in' => 'formData', 'name' => 'custom', 'description' => 'array of items', 'required' => false, 'type' => 'array', 'items' => { 'type' => 'CustomType' } }],
+              'tags' => ['custom'],
+              'operationId' => 'getCustom',
+              'responses' => { '200' => { 'description' => 'this uses a custom parameter' } }
+            }
+          }
+        )
+      end
+    end
+  end
+end

data/spec/version_spec.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe GrapeSwagger do
+  it '#version' do
+    expect(GrapeSwagger::VERSION).to_not be_nil
+    expect(GrapeSwagger::VERSION.split('.').count).to eq 3
+  end
+end