gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/api_swagger_v2_status_codes_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'http status code behaviours' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  context 'when non-default success codes are defined' do
+    let(:app) do
+      Class.new(Grape::API) do
+        desc 'Has explicit success http_codes defined' do
+          http_codes [{ code: 202, message: 'We got it!' },
+                      { code: 204, message: 'Or returned no content' },
+                      { code: 400, message: 'Bad request' }]
+        end
+
+        post '/accepting_endpoint' do
+          'We got the message!'
+        end
+        add_swagger_documentation
+      end
+    end
+
+    it 'only includes the defined http_codes' do
+      expect(subject['paths']['/accepting_endpoint']['post']['responses'].keys.sort).to eq(%w[202 204 400].sort)
+    end
+  end
+
+  context 'when success and failures are defined' do
+    let(:app) do
+      Class.new(Grape::API) do
+        desc 'Has explicit success http_codes defined' do
+          success code: 202, model: Entities::UseResponse, message: 'a changed status code'
+          failure [[400, 'Bad Request']]
+        end
+
+        post '/accepting_endpoint' do
+          'We got the message!'
+        end
+        add_swagger_documentation
+      end
+    end
+
+    it 'only includes the defined http codes' do
+      expect(subject['paths']['/accepting_endpoint']['post']['responses'].keys.sort).to eq(%w[202 400].sort)
+    end
+  end
+
+  context 'when no success codes defined' do
+    let(:app) do
+      Class.new(Grape::API) do
+        desc 'Has explicit error http_codes defined' do
+          http_codes [{ code: 400, message: 'Error!' },
+                      { code: 404, message: 'Not found' }]
+        end
+
+        post '/error_endpoint' do
+          'We got the message!'
+        end
+        add_swagger_documentation
+      end
+    end
+
+    it 'adds the success codes to the response' do
+      expect(subject['paths']['/error_endpoint']['post']['responses'].keys.sort).to eq(%w[201 400 404].sort)
+    end
+  end
+
+  context 'when success and error codes are defined' do
+    let(:app) do
+      Class.new(Grape::API) do
+        desc 'Has success and error codes defined' do
+          http_codes [{ code: 200, message: 'Found' },
+                      { code: 404, message: 'Not found' }]
+        end
+
+        get '/endpoint' do
+          'We got the message!'
+        end
+        add_swagger_documentation
+      end
+    end
+
+    it 'adds the success codes and error codes to the response' do
+      expect(subject['paths']['/endpoint']['get']['responses'].keys.sort).to eq(%w[200 404].sort)
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_type-format_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# mapping of parameter types
+# Grape                         ->  Swagger (OpenApi)
+#                                   (type format)
+# ---------------------------------------------------
+# Integer                       ->  integer int32
+# Numeric                       ->  integer int64
+# Float                         ->  number float
+# BigDecimal                    ->  number double
+# String                        ->  string
+# Symbol                        ->  string
+# Date                          ->  string date
+# DateTime                      ->  string date-time
+# Time                          ->  string date-time
+# 'password'                    ->  string password
+# 'email'                       ->  string email
+# Boolean                       ->  boolean
+# JSON                          ->  json
+# Rack::Multipart::UploadedFile ->  file
+
+describe 'type format settings' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class TypeFormatApi < Grape::API
+        desc 'full set of request data types',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::TypedDefinition
+
+        params do
+          # grape supported data types
+          requires :param_integer,   type: Integer
+          requires :param_long,      type: Numeric
+          requires :param_float,     type: Float
+          requires :param_double,    type: BigDecimal
+          optional :param_string,    type: String
+          optional :param_symbol,    type: Symbol
+          requires :param_date,      type: Date
+          requires :param_date_time, type: DateTime
+          requires :param_time,      type: Time
+          optional :param_boolean,   type: Boolean
+          optional :param_file,      type: File
+          optional :param_json,      type: JSON
+        end
+
+        post '/request_types' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::TypeFormatApi
+  end
+
+  subject do
+    get '/swagger_doc/request_types'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject['paths']['/request_types']['post']['parameters']).to eql(
+      [
+        { 'in' => 'formData', 'name' => 'param_integer', 'required' => true, 'type' => 'integer', 'format' => 'int32' },
+        { 'in' => 'formData', 'name' => 'param_long', 'required' => true, 'type' => 'integer', 'format' => 'int64' },
+        { 'in' => 'formData', 'name' => 'param_float', 'required' => true, 'type' => 'number', 'format' => 'float' },
+        { 'in' => 'formData', 'name' => 'param_double', 'required' => true, 'type' => 'number', 'format' => 'double' },
+        { 'in' => 'formData', 'name' => 'param_string', 'required' => false, 'type' => 'string' },
+        { 'in' => 'formData', 'name' => 'param_symbol', 'required' => false, 'type' => 'string' },
+        { 'in' => 'formData', 'name' => 'param_date', 'required' => true, 'type' => 'string', 'format' => 'date' },
+        { 'in' => 'formData', 'name' => 'param_date_time', 'required' => true, 'type' => 'string', 'format' => 'date-time' },
+        { 'in' => 'formData', 'name' => 'param_time', 'required' => true, 'type' => 'string', 'format' => 'date-time' },
+        { 'in' => 'formData', 'name' => 'param_boolean', 'required' => false, 'type' => 'boolean' },
+        { 'in' => 'formData', 'name' => 'param_file', 'required' => false, 'type' => 'file' },
+        { 'in' => 'formData', 'name' => 'param_json', 'required' => false, 'type' => 'json' }
+      ]
+    )
+  end
+
+  specify do
+    expect(subject['definitions']['TypedDefinition']['properties']).to eql(swagger_typed_defintion)
+  end
+end

data/spec/swagger_v2/boolean_params_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Boolean Params' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'splines' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :a_boolean, type: Grape::API::Boolean
+        optional :another_boolean, type: Grape::API::Boolean, default: false
+      end
+      post :splines do
+        { message: 'hi' }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc/splines'
+    expect(last_response.status).to eq 200
+    body = JSON.parse last_response.body
+    body['paths']['/splines']['post']['parameters']
+  end
+
+  it 'converts boolean types' do
+    expect(subject).to eq [
+      { 'in' => 'formData', 'name' => 'a_boolean', 'type' => 'boolean', 'required' => true },
+      { 'in' => 'formData', 'name' => 'another_boolean', 'type' => 'boolean', 'required' => false, 'default' => false }
+    ]
+  end
+end

data/spec/swagger_v2/default_api_spec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+# require 'grape_version'
+
+describe 'Default API' do
+  context 'with no additional options' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        desc 'This gets something.'
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    it 'documents api' do
+      expect(subject).to eq(
+        'info' => { 'title' => 'API title', 'version' => '0.0.1' },
+        'swagger' => '2.0',
+        'produces' => ['application/json'],
+        'host' => 'example.org',
+        'tags' => [{ 'name' => 'something', 'description' => 'Operations about somethings' }],
+        'paths' => {
+          '/something' => {
+            'get' => {
+              'description' => 'This gets something.',
+              'produces' => ['application/json'],
+              'tags' => ['something'],
+              'operationId' => 'getSomething',
+              'responses' => { '200' => { 'description' => 'This gets something.' } }
+            }
+          }
+        }
+      )
+    end
+
+    context 'path inside the apis array' do
+      it 'starts with a forward slash' do
+        subject['paths'].each do |path|
+          expect(path.first).to start_with '/'
+        end
+      end
+    end
+  end
+
+  context 'with additional option block given to desc', if: GrapeVersion.satisfy?('>= 0.12.0') do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        desc 'This gets something.'
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation
+      end
+    end
+
+    subject do
+      get '/swagger_doc/something'
+      JSON.parse(last_response.body)
+    end
+
+    it 'documents endpoint' do
+      expect(subject).to eq('info' => { 'title' => 'API title', 'version' => '0.0.1' },
+                            'swagger' => '2.0',
+                            'produces' => ['application/json'],
+                            'host' => 'example.org',
+                            'tags' => [{ 'name' => 'something', 'description' => 'Operations about somethings' }],
+                            'paths' => {
+                              '/something' => {
+                                'get' => {
+                                  'description' => 'This gets something.',
+                                  'produces' => ['application/json'],
+                                  'tags' => ['something'],
+                                  'operationId' => 'getSomething',
+                                  'responses' => { '200' => { 'description' => 'This gets something.' } }
+                                }
+                              }
+                            })
+    end
+  end
+
+  context 'with additional info' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        add_swagger_documentation info: {
+          title: 'My API Title',
+          description: 'A description of my API',
+          license: 'Apache 2',
+          license_url: 'http://test.com',
+          terms_of_service_url: 'http://terms.com',
+          contact_email: 'support@test.com',
+          x: {
+            logo: 'http://logo.com/img.png'
+          }
+        }
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['info']
+    end
+
+    it 'documents API title' do
+      expect(subject['title']).to eql('My API Title')
+    end
+
+    it 'documents API description' do
+      expect(subject['description']).to eql('A description of my API')
+    end
+
+    it 'should document the license' do
+      expect(subject['license']['name']).to eql('Apache 2')
+    end
+
+    it 'documents the license url' do
+      expect(subject['license']['url']).to eql('http://test.com')
+    end
+
+    it 'documents the terms of service url' do
+      expect(subject['termsOfService']).to eql('http://terms.com')
+    end
+
+    it 'documents the contact email' do
+      expect(subject['contact']['email']).to eql('support@test.com')
+    end
+
+    it 'documents the extension field' do
+      expect(subject['x-logo']).to eql('http://logo.com/img.png')
+    end
+  end
+
+  context 'with tags' do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        desc 'This gets something.'
+        get '/something' do
+          { bla: 'something' }
+        end
+        get '/somethingelse' do
+          { bla: 'somethingelse' }
+        end
+
+        add_swagger_documentation tags: [
+          { name: 'something', description: 'customized description' }
+        ]
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    it 'documents the customized tag' do
+      expect(subject['tags']).to eql(
+        [
+          { 'name' => 'somethingelse', 'description' => 'Operations about somethingelses' },
+          { 'name' => 'something', 'description' => 'customized description' }
+        ]
+      )
+    end
+  end
+end

data/spec/swagger_v2/deprecated_field_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'deprecated endpoint' do
+  def app
+    Class.new(Grape::API) do
+      desc 'Deprecated endpoint', deprecated: true
+      get '/foobar' do
+        { foo: 'bar' }
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body)
+  end
+
+  it 'includes the deprecated field' do
+    expect(subject['paths']['/foobar']['get']['deprecated']).to eql(true)
+  end
+end

data/spec/swagger_v2/description_not_initialized_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'has no description, if details or description are nil' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class GfmRcDetailApi < Grape::API
+        format :json
+
+        desc nil,
+             detail: nil,
+             entity: Entities::UseResponse,
+             failure: [{ code: 400, model: Entities::ApiError }]
+        get '/use_gfm_rc_detail' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::GfmRcDetailApi
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject['paths']['/use_gfm_rc_detail']['get']).not_to include('description')
+    expect(subject['paths']['/use_gfm_rc_detail']['get']['description']).to eql(nil)
+  end
+end

data/spec/swagger_v2/endpoint_versioned_path_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Grape::Endpoint#path_and_definitions' do
+  context 'when mounting an API once' do
+    let(:item) do
+      Class.new(Grape::API) do
+        version 'v1', using: :path
+
+        resource :item do
+          get '/'
+        end
+      end
+    end
+
+    let(:api) do
+      item_api = item
+
+      Class.new(Grape::API) do
+        mount item_api
+        add_swagger_documentation add_version: true
+      end
+    end
+
+    let(:options) { { add_version: true } }
+    let(:target_routes) { api.combined_namespace_routes }
+
+    subject { api.endpoints[0].path_and_definition_objects(target_routes, options) }
+
+    it 'is returning a versioned path' do
+      expect(subject[0].keys[0]).to eq '/v1/item'
+    end
+
+    it 'tags the endpoint with the resource name' do
+      expect(subject.first['/v1/item'][:get][:tags]).to eq ['item']
+    end
+
+    context 'when custom tags are specified' do
+      let(:item) do
+        Class.new(Grape::API) do
+          version 'v1', using: :path
+
+          resource :item do
+            desc 'Item description', tags: ['special-item']
+            get '/'
+          end
+        end
+      end
+
+      it 'tags the endpoint with the custom tags' do
+        expect(subject.first['/v1/item'][:get][:tags]).to eq ['special-item']
+      end
+    end
+
+    context 'when parameter with a custom type is specified' do
+      let(:item) do
+        Class.new(Grape::API) do
+          Color = Struct.new(:value) do
+            def self.parse(value)
+              new(value: value)
+            end
+          end
+
+          class ColorEntity < Grape::Entity
+            expose :value
+          end
+
+          version 'v1', using: :path
+
+          resource :item do
+            params do
+              requires :root, type: Hash do
+                optional :color, type: Color, documentation: { type: ColorEntity }
+              end
+            end
+            post '/'
+          end
+        end
+      end
+
+      it 'creates a reference to the model instead of using the non-existent type' do
+        color = subject.dig(1, 'postV1Item', :properties, :root, :properties, :color)
+        expect(color).not_to eq(type: 'ColorEntity')
+        expect(color).to eq('$ref' => '#/definitions/ColorEntity')
+      end
+    end
+  end
+
+  context 'when mounting an API more than once', if: GrapeVersion.satisfy?('>= 1.2.0') do
+    let(:item) do
+      Class.new(Grape::API) do
+        resource :item do
+          desc 'Item description', tags: [configuration[:tag] || 'item']
+          get '/'
+        end
+      end
+    end
+
+    let(:api) do
+      item_api = item
+      Class.new(Grape::API) do
+        version 'v1', using: :path do
+          mount item_api
+        end
+
+        version 'v2', using: :path do
+          mount item_api, with: { tag: 'special-item' }
+        end
+
+        add_swagger_documentation add_version: true
+      end
+    end
+
+    let(:options) { { add_version: true } }
+    let(:target_routes) { api.combined_namespace_routes }
+
+    subject { api.endpoints[0].path_and_definition_objects(target_routes, options) }
+
+    it 'retrieves both apis respecting their configured tags' do
+      expect(subject.first['/v1/item'][:get][:tags]).to eq ['item']
+      expect(subject.first['/v2/item'][:get][:tags]).to eq ['special-item']
+    end
+
+    it 'retrieves both apis with descriptions' do
+      expect(subject.first['/v1/item'][:get][:description]).to eq 'Item description'
+      expect(subject.first['/v2/item'][:get][:description]).to eq 'Item description'
+    end
+  end
+end

data/spec/swagger_v2/errors_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Errors' do
+  describe 'Empty model error' do
+    let!(:app) do
+      Class.new(Grape::API) do
+        format :json
+
+        desc 'Empty model get.' do
+          http_codes [
+            { code: 200, message: 'get Empty model', model: EmptyClass }
+          ]
+        end
+        get '/empty_model' do
+          something = OpenStruct.new text: 'something'
+          present something, with: EmptyClass
+        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
+
+    it 'should raise SwaggerSpec exception' do
+      expect { get '/v3/swagger_doc' }.to raise_error(GrapeSwagger::Errors::SwaggerSpec, "Empty model EmptyClass, swagger 2.0 doesn't support empty definitions.")
+    end
+  end
+
+  describe 'Parser not found error' do
+    let!(:app) do
+      Class.new(Grape::API) do
+        format :json
+
+        desc 'Wrong model get.' do
+          http_codes [
+            { code: 200, message: 'get Wrong model', model: Hash }
+          ]
+        end
+        get '/wrong_model' do
+          something = OpenStruct.new text: 'something'
+          present something, with: Hash
+        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
+
+    it 'should raise UnregisteredParser exception' do
+      expect { get '/v3/swagger_doc' }.to raise_error(GrapeSwagger::Errors::UnregisteredParser, 'No parser registered for Hash.')
+    end
+  end
+end