gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/api_swagger_v2_response_with_headers_spec.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response with headers' do
+  # include_context "#{MODEL_PARSER} swagger header"
+
+  before :all do
+    module TheApi
+      class ResponseApiHeaders < Grape::API
+        format :json
+
+        desc 'This returns headers' do
+          success model: Entities::UseResponse, headers: { 'Location' => { description: 'Location of resource', type: 'string' } }
+          failure [[404, 'NotFound', Entities::ApiError, { 'application/json' => { code: 404, message: 'Not found' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
+        end
+        get '/response_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'A 204 can have headers too' do
+          foo = { status: 204, message: 'No content', headers: { 'Location' => { description: 'Location of resource', type: 'string' } } }
+          success foo
+          failure [[400, 'Bad Request', Entities::ApiError, { 'application/json' => { code: 400, message: 'Bad request' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
+        end
+        delete '/no_content_response_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'A file can have headers too' do
+          foo = { status: 200, model: 'File', headers: { 'Cache-Control': { description: 'Directive for caching', type: 'string' } } }
+          success foo
+          failure [[404, 'NotFound', Entities::ApiError, { 'application/json' => { code: 404, message: 'Not found' } }, { 'Date' => { description: 'Date of failure', type: 'string' } }]]
+        end
+        get '/file_response_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This syntax also returns headers' do
+          success model: Entities::UseResponse, headers: { 'Location' => { description: 'Location of resource', type: 'string' } }
+          failure [
+            {
+              code: 404,
+              message: 'NotFound',
+              model: Entities::ApiError,
+              headers: { 'Date' => { description: 'Date of failure', type: 'string' } }
+            },
+            {
+              code: 400,
+              message: 'BadRequest',
+              model: Entities::ApiError,
+              headers: { 'Date' => { description: 'Date of failure', type: 'string' } }
+            }
+          ]
+        end
+        get '/response_failure_headers' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This does not return headers' do
+          success model: Entities::UseResponse
+          failure [[404, 'NotFound', Entities::ApiError]]
+        end
+        get '/response_no_headers' do
+          { 'declared_params' => declared(params) }
+        end
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiHeaders
+  end
+
+  describe 'response headers' do
+    let(:header_200) do
+      { 'Location' => { 'description' => 'Location of resource', 'type' => 'string' } }
+    end
+    let(:header_404) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+    let(:examples_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_headers']['get']).to eql(
+        'description' => 'This returns headers',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns headers', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'headers' => header_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => examples_404, 'headers' => header_404 }
+        },
+        'tags' => ['response_headers'],
+        'operationId' => 'getResponseHeaders'
+      )
+    end
+  end
+
+  describe 'no content response headers' do
+    let(:header_204) do
+      { 'Location' => { 'description' => 'Location of resource', 'type' => 'string' } }
+    end
+    let(:header_400) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+    let(:examples_400) do
+      { 'application/json' => { 'code' => 400, 'message' => 'Bad request' } }
+    end
+
+    subject do
+      get '/swagger_doc/no_content_response_headers', {}
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/no_content_response_headers']['delete']).to eql(
+        'description' => 'A 204 can have headers too',
+        'produces' => ['application/json'],
+        'responses' => {
+          '204' => { 'description' => 'No content', 'headers' => header_204 },
+          '400' => { 'description' => 'Bad Request', 'headers' => header_400, 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => examples_400 }
+        },
+        'tags' => ['no_content_response_headers'],
+        'operationId' => 'deleteNoContentResponseHeaders'
+      )
+    end
+  end
+
+  describe 'file response headers' do
+    let(:header_200) do
+      { 'Cache-Control' => { 'description' => 'Directive for caching', 'type' => 'string' } }
+    end
+    let(:header_404) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+    let(:examples_404) do
+      { 'application/json' => { 'code' => 404, 'message' => 'Not found' } }
+    end
+
+    subject do
+      get '/swagger_doc/file_response_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/file_response_headers']['get']).to eql(
+        'description' => 'A file can have headers too',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'A file can have headers too', 'headers' => header_200, 'schema' => { 'type' => 'file' } },
+          '404' => { 'description' => 'NotFound', 'headers' => header_404, 'schema' => { '$ref' => '#/definitions/ApiError' }, 'examples' => examples_404 }
+        },
+        'tags' => ['file_response_headers'],
+        'operationId' => 'getFileResponseHeaders'
+      )
+    end
+  end
+
+  describe 'response failure headers' do
+    let(:header_200) do
+      { 'Location' => { 'description' => 'Location of resource', 'type' => 'string' } }
+    end
+    let(:header_404) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+    let(:header_400) do
+      { 'Date' => { 'description' => 'Date of failure', 'type' => 'string' } }
+    end
+
+    subject do
+      get '/swagger_doc/response_failure_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_failure_headers']['get']).to eql(
+        'description' => 'This syntax also returns headers',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This syntax also returns headers', 'schema' => { '$ref' => '#/definitions/UseResponse' }, 'headers' => header_200 },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'headers' => header_404 },
+          '400' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' }, 'headers' => header_400 }
+        },
+        'tags' => ['response_failure_headers'],
+        'operationId' => 'getResponseFailureHeaders'
+      )
+    end
+  end
+
+  describe 'response no headers' do
+    subject do
+      get '/swagger_doc/response_no_headers'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/response_no_headers']['get']).to eql(
+        'description' => 'This does not return headers',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This does not return headers', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '404' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['response_no_headers'],
+        'operationId' => 'getResponseNoHeaders'
+      )
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_response_with_models_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApiModels < Grape::API
+        format :json
+
+        desc 'This returns something',
+             success: [{ code: 200 }],
+             failure: [
+               { code: 400, message: 'NotFound', model: '' },
+               { code: 404, message: 'BadRequest', model: Entities::ApiError }
+             ]
+        get '/use-response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation(models: [Entities::UseResponse])
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiModels
+  end
+
+  describe 'uses entity as response object implicitly with route name' do
+    subject do
+      get '/swagger_doc/use-response'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use-response']['get']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'This returns something', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
+          '400' => { 'description' => 'NotFound' },
+          '404' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['use-response'],
+        'operationId' => 'getUseResponse'
+      )
+      expect(subject['definitions']).to eql(swagger_entity_as_response_object)
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_response_with_root_spec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response with root' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApiWithRoot < Grape::API
+        format :json
+
+        desc 'This returns something',
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/ordinary_response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+             is_array: true,
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_array' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: true
+        desc 'This returns something',
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_root' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: true
+        desc 'This returns underscored root',
+             http_codes: [{ code: 200, model: Entities::ApiError }]
+        get '/response_with_root_underscore' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: true
+        desc 'This returns something',
+             is_array: true,
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_array_and_root' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: 'custom_root'
+        desc 'This returns something',
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_custom_root' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiWithRoot
+  end
+
+  describe 'GET /ordinary_response' do
+    subject do
+      get '/swagger_doc/ordinary_response'
+      JSON.parse(last_response.body)
+    end
+
+    it 'does not add root or array' do
+      schema = subject.dig('paths', '/ordinary_response', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        '$ref' => '#/definitions/Something'
+      )
+    end
+  end
+
+  describe 'GET /response_with_array' do
+    subject do
+      get '/swagger_doc/response_with_array'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds array to the response' do
+      schema = subject.dig('paths', '/response_with_array', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'array', 'items' => { '$ref' => '#/definitions/Something' }
+      )
+    end
+  end
+
+  describe 'GET /response_with_root' do
+    subject do
+      get '/swagger_doc/response_with_root'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root to the response' do
+      schema = subject.dig('paths', '/response_with_root', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => { 'something' => { '$ref' => '#/definitions/Something' } }
+      )
+    end
+  end
+
+  describe 'GET /response_with_root_underscore' do
+    subject do
+      get '/swagger_doc/response_with_root_underscore'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root to the response' do
+      schema = subject.dig('paths', '/response_with_root_underscore', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => { 'api_error' => { '$ref' => '#/definitions/ApiError' } }
+      )
+    end
+  end
+
+  describe 'GET /response_with_array_and_root' do
+    subject do
+      get '/swagger_doc/response_with_array_and_root'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root and array to the response' do
+      schema = subject.dig('paths', '/response_with_array_and_root', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => {
+          'somethings' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/Something' } }
+        }
+      )
+    end
+  end
+
+  describe 'GET /response_with_custom_root' do
+    subject do
+      get '/swagger_doc/response_with_custom_root'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root to the response' do
+      schema = subject.dig('paths', '/response_with_custom_root', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => { 'custom_root' => { '$ref' => '#/definitions/Something' } }
+      )
+    end
+  end
+end

data/spec/swagger_v2/api_swagger_v2_spec.rb

@@ -0,0 +1,245 @@
+# 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
+
+      #  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 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
+
+  describe 'whole documentation' do
+    subject do
+      get '/v3/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    describe 'swagger object' do
+      describe 'required keys' do
+        it { expect(subject.keys).to include 'swagger' }
+        it { expect(subject['swagger']).to eql '2.0' }
+        it { expect(subject.keys).to include 'info' }
+        it { expect(subject['info']).to be_a Hash }
+        it { expect(subject.keys).to include 'paths' }
+        it { expect(subject['paths']).to be_a Hash }
+      end
+
+      describe 'info object required keys' do
+        let(:info) { subject['info'] }
+
+        it { expect(info.keys).to include 'title' }
+        it { expect(info['title']).to be_a String }
+        it { expect(info.keys).to include 'version' }
+        it { expect(info['version']).to be_a String }
+
+        describe 'license object' do
+          let(:license) { subject['info']['license'] }
+
+          it { expect(license.keys).to include 'name' }
+          it { expect(license['name']).to be_a String }
+          it { expect(license.keys).to include 'url' }
+          it { expect(license['url']).to be_a String }
+        end
+
+        describe 'contact object' do
+          let(:contact) { subject['info']['contact'] }
+
+          it { expect(contact.keys).to include 'name' }
+          it { expect(contact['name']).to be_a String  }
+          it { expect(contact.keys).to include 'email' }
+          it { expect(contact['email']).to be_a String }
+          it { expect(contact.keys).to include 'url' }
+          it { expect(contact['url']).to be_a String }
+        end
+
+        describe 'global tags' do
+          let(:tags) { subject['tags'] }
+
+          it { expect(tags).to be_a Array }
+          it { expect(tags).not_to be_empty }
+        end
+      end
+
+      describe 'path object' do
+        let(:paths) { subject['paths'] }
+
+        it 'hides documentation paths per default' do
+          expect(paths.keys).not_to include '/swagger_doc', '/swagger_doc/{name}'
+        end
+
+        specify do
+          paths.each_pair do |path, value|
+            expect(path).to start_with('/')
+            expect(value).to be_a Hash
+            expect(value).not_to be_empty
+
+            value.each do |method, declaration|
+              expect(http_verbs).to include method
+              expect(declaration).to have_key('responses')
+
+              declaration['responses'].each do |status_code, response|
+                expect(status_code).to match(/\d{3}/)
+                expect(response).to have_key('description')
+              end
+            end
+          end
+        end
+      end
+
+      describe 'definitions object' do
+        let(:definitions) { subject['definitions'] }
+
+        specify do
+          definitions.each do |model, properties|
+            expect(model).to match(/\w+/)
+            expect(properties).to have_key('properties')
+          end
+        end
+      end
+    end
+
+    describe 'swagger file' do
+      it do
+        expect(subject).to eql swagger_json
+      end
+    end
+  end
+
+  describe 'specific resource documentation' do
+    subject do
+      get '/v3/swagger_doc/other_thing'
+      JSON.parse(last_response.body)
+    end
+
+    let(:tags) { subject['tags'] }
+    specify do
+      expect(tags).to eql [
+        {
+          'name' => 'other_thing',
+          'description' => 'Operations about other_things'
+        }
+      ]
+    end
+  end
+end