gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/api_swagger_v2_param_type_spec.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'setting of param type, such as `query`, `path`, `formData`, `body`, `header`' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ParamTypeApi < Grape::API
+        # using `:param_type`
+        desc 'full set of request param types',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          optional :in_query, type: String, documentation: { param_type: 'query' }
+          optional :in_header, type: String, documentation: { param_type: 'header' }
+        end
+
+        get '/defined_param_type' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'full set of request param types',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          requires :in_path, type: Integer
+          optional :in_query, type: String, documentation: { param_type: 'query' }
+          optional :in_header, type: String, documentation: { param_type: 'header' }
+        end
+
+        get '/defined_param_type/:in_path' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'full set of request param types',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          optional :in_path, type: Integer
+          optional :in_query, type: String, documentation: { param_type: 'query' }
+          optional :in_header, type: String, documentation: { param_type: 'header' }
+        end
+
+        delete '/defined_param_type/:in_path' do
+          { 'declared_params' => declared(params) }
+        end
+
+        # using `:in`
+        desc 'full set of request param types using `:in`',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          optional :in_query, type: String, documentation: { in: 'query' }
+          optional :in_header, type: String, documentation: { in: 'header' }
+        end
+
+        get '/defined_in' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'full set of request param types using `:in`',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          requires :in_path, type: Integer
+          optional :in_query, type: String, documentation: { in: 'query' }
+          optional :in_header, type: String, documentation: { in: 'header' }
+        end
+
+        get '/defined_in/:in_path' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'full set of request param types using `:in`',
+          consumes: ['application/x-www-form-urlencoded']
+        params do
+          optional :in_path, type: Integer
+          optional :in_query, type: String, documentation: { in: 'query' }
+          optional :in_header, type: String, documentation: { in: 'header' }
+        end
+
+        delete '/defined_in/:in_path' do
+          { 'declared_params' => declared(params) }
+        end
+
+        # file
+        desc 'file download',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          requires :name, type: String
+        end
+
+        get '/download' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'file upload',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: Entities::UseResponse
+        params do
+          requires :name, type: File
+        end
+
+        post '/upload' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ParamTypeApi
+  end
+
+  describe 'foo' do
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type/{in_path}']['delete']['responses']).to eql(
+        '200' => {
+          'description' => 'full set of request param types',
+          'schema' => { '$ref' => '#/definitions/UseResponse' }
+        }
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in/{in_path}']['delete']['responses']).to eql(
+        '204' => {
+          'description' => 'full set of request param types using `:in`'
+        }
+      )
+    end
+  end
+
+  describe 'defined param types' do
+    subject do
+      get '/swagger_doc/defined_param_type'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type']['get']['parameters']).to eql(
+        [
+          { 'in' => 'query', 'name' => 'in_query', 'required' => false, 'type' => 'string' },
+          { 'in' => 'header', 'name' => 'in_header', 'required' => false, 'type' => 'string' }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type/{in_path}']['get']['parameters']).to eql(
+        [
+          { 'in' => 'path', 'name' => 'in_path', 'required' => true, 'type' => 'integer', 'format' => 'int32' },
+          { 'in' => 'query', 'name' => 'in_query', 'required' => false, 'type' => 'string' },
+          { 'in' => 'header', 'name' => 'in_header', 'required' => false, 'type' => 'string' }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/defined_param_type/{in_path}']['delete']['parameters']).to eql(
+        [
+          { 'in' => 'path', 'name' => 'in_path', 'required' => true, 'type' => 'integer', 'format' => 'int32' },
+          { 'in' => 'query', 'name' => 'in_query', 'required' => false, 'type' => 'string' },
+          { 'in' => 'header', 'name' => 'in_header', 'required' => false, 'type' => 'string' }
+        ]
+      )
+    end
+  end
+
+  describe 'defined param types with `:in`' do
+    subject do
+      get '/swagger_doc/defined_in'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in']['get']['parameters']).to eql(
+        [
+          { 'in' => 'query', 'name' => 'in_query', 'required' => false, 'type' => 'string' },
+          { 'in' => 'header', 'name' => 'in_header', 'required' => false, 'type' => 'string' }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in/{in_path}']['get']['parameters']).to eql(
+        [
+          { 'in' => 'path', 'name' => 'in_path', 'required' => true, 'type' => 'integer', 'format' => 'int32' },
+          { 'in' => 'query', 'name' => 'in_query', 'required' => false, 'type' => 'string' },
+          { 'in' => 'header', 'name' => 'in_header', 'required' => false, 'type' => 'string' }
+        ]
+      )
+    end
+
+    specify do
+      expect(subject['paths']['/defined_in/{in_path}']['delete']['parameters']).to eql(
+        [
+          { 'in' => 'path', 'name' => 'in_path', 'required' => true, 'type' => 'integer', 'format' => 'int32' },
+          { 'in' => 'query', 'name' => 'in_query', 'required' => false, 'type' => 'string' },
+          { 'in' => 'header', 'name' => 'in_header', 'required' => false, 'type' => 'string' }
+        ]
+      )
+    end
+  end
+
+  describe 'file' do
+    describe 'upload' do
+      subject do
+        get '/swagger_doc/upload'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']['/upload']['post']['parameters']).to eql(
+          [
+            { 'in' => 'formData', 'name' => 'name', 'required' => true, 'type' => 'file' }
+          ]
+        )
+      end
+    end
+
+    describe 'download' do
+      subject do
+        get '/swagger_doc/download'
+        JSON.parse(last_response.body)
+      end
+
+      specify do
+        expect(subject['paths']['/download']['get']['parameters']).to eql(
+          [
+            { 'in' => 'query', 'name' => 'name', 'required' => true, 'type' => 'string' }
+          ]
+        )
+      end
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_request_params_fix_spec.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'additional parameter settings' do
+  before :all do
+    module TheApi
+      class RequestParamFix < Grape::API
+        resource :bookings do
+          desc 'Update booking' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          params do
+            optional :name, type: String
+          end
+          put ':id' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'Get booking details' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          get ':id' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'Get booking details by access_number' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          get '/conf/:access_number' do
+            { 'declared_params' => declared(params) }
+          end
+
+          desc 'Remove booking' do
+            consumes ['application/x-www-form-urlencoded']
+          end
+          delete ':id' do
+            { 'declared_params' => declared(params) }
+          end
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::RequestParamFix
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  specify do
+    expect(subject['paths']['/bookings/{id}']['put']['parameters'].sort_by { |p| p['name'] }).to eql(
+      [
+        { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true },
+        { 'in' => 'formData', 'name' => 'name', 'type' => 'string', 'required' => false }
+      ]
+    )
+  end
+
+  specify do
+    expect(subject['paths']['/bookings/{id}']['get']['parameters']).to eql(
+      [
+        { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }
+      ]
+    )
+  end
+
+  specify do
+    expect(subject['paths']['/bookings/{id}']['delete']['parameters']).to eql(
+      [
+        { 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }
+      ]
+    )
+  end
+end

data/spec/swagger_v2/api_swagger_v2_response_spec.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApi < Grape::API
+        format :json
+
+        desc 'This returns something',
+          consumes: ['application/x-www-form-urlencoded'],
+          params: Entities::UseResponse.documentation,
+          failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        post '/params_given' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+          consumes: ['application/x-www-form-urlencoded'],
+          entity: Entities::UseResponse,
+          failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/entity_response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+          consumes: ['application/x-www-form-urlencoded'],
+          entity: Entities::UseItemResponseAsType,
+          failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/nested_type' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+          consumes: ['application/x-www-form-urlencoded'],
+          success: [
+            { code: 200, message: 'Request has succeeded' },
+            { code: 201, message: 'Successful Operation' },
+            { code: 204, message: 'Request was fulfilled' }
+          ],
+          failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/multiple-success-responses' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApi
+  end
+
+  describe 'uses nested type as response object' do
+    subject do
+      get '/swagger_doc/nested_type'
+      JSON.parse(last_response.body)
+    end
+    specify do
+      expect(subject['paths']['/nested_type']['get']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns something', 'schema' => { '$ref' => '#/definitions/UseItemResponseAsType' } },
+          '400' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['nested_type'],
+        'operationId' => 'getNestedType'
+      )
+      expect(subject['definitions']).to eql(swagger_nested_type)
+    end
+  end
+
+  describe 'uses entity as response object' do
+    subject do
+      get '/swagger_doc/entity_response'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/entity_response']['get']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns something', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '400' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['entity_response'],
+        'operationId' => 'getEntityResponse'
+      )
+      expect(subject['definitions']).to eql(swagger_entity_as_response_object)
+    end
+  end
+
+  describe 'uses params as response object' do
+    subject do
+      get '/swagger_doc/params_given'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/params_given']['post']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'consumes' => ['application/x-www-form-urlencoded'],
+        'parameters' => [
+          { 'in' => 'formData', 'name' => 'description', 'type' => 'string', 'required' => false },
+          { 'in' => 'formData', 'name' => '$responses', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => false }
+        ],
+        'responses' => {
+          '201' => { 'description' => 'This returns something' },
+          '400' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['params_given'],
+        'operationId' => 'postParamsGiven'
+      )
+      expect(subject['definitions']).to eql(swagger_params_as_response_object)
+    end
+  end
+
+  describe 'uses params as response object when response contains multiple values for success' do
+    subject do
+      get '/swagger_doc/multiple-success-responses'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/multiple-success-responses']['get']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'Request has succeeded' },
+          '201' => { 'description' => 'Successful Operation' },
+          '204' => { 'description' => 'Request was fulfilled' },
+          '400' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['multiple-success-responses'],
+        'operationId' => 'getMultipleSuccessResponses'
+      )
+      expect(subject['definitions']).to eql(swagger_params_as_response_object)
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_response_with_examples_spec.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response with examples' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApiExamples < Grape::API
+        format :json
+
+        desc 'This returns examples' do
+          success model: Entities::UseResponse, examples: { 'application/json' => { description: 'Names list', items: [{ id: '123', name: 'John' }] } }
+          failure [[404, 'NotFound', Entities::ApiError, { 'application/json' => { code: 404, message: 'Not found' } }]]
+        end
+        get '/response_examples' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This syntax also returns examples' do
+          success model: Entities::UseResponse, examples: { 'application/json' => { description: 'Names list', items: [{ id: '123', name: 'John' }] } }
+          failure [
+            {
+              code: 404,
+              message: 'NotFound',
+              model: Entities::ApiError,
+              examples: { 'application/json' => { code: 404, message: 'Not found' } }
+            },
+            {
+              code: 400,
+              message: 'BadRequest',
+              model: Entities::ApiError,
+              examples: { 'application/json' => { code: 400, message: 'Bad Request' } }
+            }
+          ]
+        end
+        get '/response_failure_examples' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This does not return examples' do
+          success model: Entities::UseResponse
+          failure [[404, 'NotFound', Entities::ApiError]]
+        end
+        get '/response_no_examples' do
+          { 'declared_params' => declared(params) }
+        end
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiExamples
+  end
+
+  describe 'response examples' do
+    let(:example_200) do
+      { 'application/json' => { 'description' => 'Names list', 'items' => [{ 'id' => '123', 'name' => 'John' }] } }
+    end
+    let(:example_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_examples']['get']).to eql(
+        'description' => 'This returns examples',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns examples', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'examples' => example_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => example_404 }
+        },
+        'tags' => ['response_examples'],
+        'operationId' => 'getResponseExamples'
+      )
+    end
+  end
+
+  describe 'response failure examples' do
+    let(:example_200) do
+      { 'application/json' => { 'description' => 'Names list', 'items' => [{ 'id' => '123', 'name' => 'John' }] } }
+    end
+    let(:example_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+    let(:example_400) do
+      { 'application/json' => { 'code' => 400, 'message' => 'Bad Request' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_failure_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_failure_examples']['get']).to eql(
+        'description' => 'This syntax also returns examples',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This syntax also returns examples', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'examples' => example_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => example_404 },
+          '400' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => example_400 }
+        },
+        'tags' => ['response_failure_examples'],
+        'operationId' => 'getResponseFailureExamples'
+      )
+    end
+  end
+
+  describe 'response no examples' do
+    subject do
+      get '/swagger_doc/response_no_examples'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_no_examples']['get']).to eql(
+        'description' => 'This does not return examples',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This does not return examples', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['response_no_examples'],
+        'operationId' => 'getResponseNoExamples'
+      )
+    end
+  end
+end