gitlab-grape-swagger 1.5.0

data/spec/swagger_v2/float_api_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Float 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_float, type: Float
+      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 float types' do
+    expect(subject).to eq [
+      { 'in' => 'formData', 'name' => 'a_float', 'type' => 'number', 'required' => true, 'format' => 'float' }
+    ]
+  end
+end

data/spec/swagger_v2/form_params_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Form Params' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      desc 'get items' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :name, type: String, desc: 'name of item'
+      end
+      post '/items' do
+        {}
+      end
+
+      desc 'get item' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :id, type: Integer, desc: 'id of item'
+        requires :name, type: String, desc: 'name of item'
+        requires :conditions, type: Integer, desc: 'conditions of item', values: [1, 2, 3]
+      end
+      put '/items/:id' do
+        {}
+      end
+
+      params do
+        requires :id, type: Integer, desc: 'id of item'
+        requires :name, type: String, desc: 'name of item'
+        optional :conditions, type: String, desc: 'conditions of item', values: proc { %w[1 2] }
+      end
+      patch '/items/:id' do
+        {}
+      end
+
+      desc 'create item' do
+        consumes ['application/x-www-form-urlencoded']
+      end
+      params do
+        requires :id, type: Integer, desc: 'id of item'
+        requires :name, type: String, desc: 'name of item'
+        optional :conditions, type: Symbol, desc: 'conditions of item', values: %i[one two]
+      end
+      post '/items/:id' do
+        {}
+      end
+
+      add_swagger_documentation
+    end
+  end
+
+  subject do
+    get '/swagger_doc/items'
+    JSON.parse(last_response.body)
+  end
+
+  it 'retrieves the documentation form params' do
+    expect(subject['paths'].length).to eq 2
+    expect(subject['paths'].keys).to include('/items', '/items/{id}')
+    expect(subject['paths']['/items'].keys).to include 'post'
+    expect(subject['paths']['/items/{id}'].keys).to include('post', 'patch', 'put')
+  end
+
+  it 'treats Symbol parameter as form param' do
+    expect(subject['paths']['/items/{id}']['post']['parameters']).to eq [
+      { 'in' => 'path', 'name' => 'id', 'description' => 'id of item', 'type' => 'integer', 'required' => true, 'format' => 'int32' },
+      { 'in' => 'formData', 'name' => 'name', 'description' => 'name of item', 'type' => 'string', 'required' => true },
+      { 'in' => 'formData', 'name' => 'conditions', 'description' => 'conditions of item', 'type' => 'string', 'required' => false, 'enum' => %w[one two] }
+    ]
+  end
+end

data/spec/swagger_v2/grape-swagger_spec.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe GrapeInstance do
+  it 'added combined-routes' do
+    expect(described_class).to respond_to :combined_routes
+  end
+
+  it 'added add_swagger_documentation' do
+    expect(described_class).to respond_to :add_swagger_documentation
+  end
+
+  it 'added combined-namespaces' do
+    expect(described_class).to respond_to :combined_namespaces
+  end
+end

data/spec/swagger_v2/guarded_endpoint_spec.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+class SampleAuth < Grape::Middleware::Base
+  module AuthMethods
+    attr_accessor :access_token
+
+    def protected_endpoint=(protected)
+      @protected_endpoint = protected
+    end
+
+    def protected_endpoint?
+      @protected_endpoint || false
+    end
+
+    def resource_owner
+      @resource_owner = true if access_token == '12345'
+    end
+  end
+
+  def context
+    env['api.endpoint']
+  end
+
+  def before
+    context.extend(SampleAuth::AuthMethods)
+    context.protected_endpoint = context.options[:route_options][:auth].present?
+
+    return unless context.protected_endpoint?
+
+    scopes = context.options[:route_options][:auth][:scopes]
+    authorize!(*scopes) unless scopes.include? false
+    context.access_token = env['HTTP_AUTHORIZATION']
+  end
+end
+
+module Extension
+  def sample_auth(*scopes)
+    description = route_setting(:description) || route_setting(:description, {})
+    description[:auth] = { scopes: scopes }
+  end
+
+  GrapeInstance.extend self
+end
+
+describe 'a guarded api endpoint' do
+  before :all do
+    class GuardedMountedApi < Grape::API
+      resource_owner_valid = proc { |token_owner = nil| token_owner.nil? }
+
+      desc 'Show endpoint if authenticated'
+      route_setting :swagger, hidden: resource_owner_valid
+      get '/auth' do
+        { foo: 'bar' }
+      end
+    end
+
+    class GuardedApi < Grape::API
+      mount GuardedMountedApi
+      add_swagger_documentation endpoint_auth_wrapper: SampleAuth,
+                                swagger_endpoint_guard: 'sample_auth false',
+                                token_owner: 'resource_owner'
+    end
+  end
+
+  def app
+    GuardedApi
+  end
+
+  let(:endpoint) { '/swagger_doc.json' }
+  let(:auth_token) { nil }
+
+  subject do
+    get endpoint, {}, 'HTTP_AUTHORIZATION' => auth_token
+    JSON.parse(last_response.body)
+  end
+
+  context 'accessing the main doc endpoint' do
+    let(:endpoint) { '/swagger_doc.json' }
+
+    context 'when a correct token is passed with the request' do
+      let(:auth_token) { '12345' }
+
+      it 'retrieves swagger-documentation for the endpoint' 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' => 'auth', 'description' => 'Operations about auths' }],
+          'paths' => {
+            '/auth' => {
+              'get' => {
+                'description' => 'Show endpoint if authenticated',
+                'produces' => ['application/json'],
+                'tags' => ['auth'],
+                'operationId' => 'getAuth',
+                'responses' => { '200' => { 'description' => 'Show endpoint if authenticated' } }
+              }
+            }
+          }
+        )
+      end
+    end
+
+    context 'when a bad token is passed with the request' do
+      let(:auth_token) { '123456' }
+
+      it 'does not retrieve swagger-documentation for the endpoint - only the info_object' 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'
+        )
+      end
+    end
+  end
+
+  context 'accessing the tag specific endpoint' do
+    let(:endpoint) { '/swagger_doc/auth.json' }
+
+    context 'when a correct token is passed with the request' do
+      let(:auth_token) { '12345' }
+
+      it 'retrieves swagger-documentation for the endpoint' 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' => 'auth', 'description' => 'Operations about auths' }],
+          'paths' => {
+            '/auth' => {
+              'get' => {
+                'description' => 'Show endpoint if authenticated',
+                'produces' => ['application/json'],
+                'tags' => ['auth'],
+                'operationId' => 'getAuth',
+                'responses' => { '200' => { 'description' => 'Show endpoint if authenticated' } }
+              }
+            }
+          }
+        )
+      end
+    end
+
+    context 'when a bad token is passed with the request' do
+      let(:auth_token) { '123456' }
+
+      it 'does not retrieve swagger-documentation for the endpoint - only the info_object' 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'
+        )
+      end
+    end
+  end
+end

data/spec/swagger_v2/hide_api_spec.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'a hide mounted api' do
+  before :all do
+    class HideMountedApi < Grape::API
+      desc 'Show this endpoint'
+      get '/simple' do
+        { foo: 'bar' }
+      end
+
+      desc 'Hide this endpoint', hidden: true
+      get '/hide' do
+        { foo: 'bar' }
+      end
+
+      desc 'Hide this endpoint using route setting'
+      route_setting :swagger, hidden: true
+      get '/hide_as_well' do
+        { foo: 'bar' }
+      end
+
+      desc 'Lazily show endpoint', hidden: -> { false }
+      get '/lazy' do
+        { foo: 'bar' }
+      end
+    end
+
+    class HideApi < Grape::API
+      mount HideMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    HideApi
+  end
+
+  subject do
+    get '/swagger_doc.json'
+    JSON.parse(last_response.body)
+  end
+
+  it "retrieves swagger-documentation that doesn't include hidden endpoints" 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' => 'lazy', 'description' => 'Operations about lazies' }],
+      'paths' => {
+        '/simple' => {
+          'get' => {
+            'description' => 'Show this endpoint',
+            'produces' => ['application/json'],
+            'tags' => ['simple'],
+            'operationId' => 'getSimple',
+            'responses' => { '200' => { 'description' => 'Show this endpoint' } }
+          }
+        },
+        '/lazy' => {
+          'get' => {
+            'description' => 'Lazily show endpoint',
+            'produces' => ['application/json'],
+            'tags' => ['lazy'],
+            'operationId' => 'getLazy',
+            'responses' => { '200' => { 'description' => 'Lazily show endpoint' } }
+          }
+        }
+      }
+    )
+  end
+end
+
+describe 'a hide mounted api with same namespace' do
+  before :all do
+    class HideNamespaceMountedApi < Grape::API
+      desc 'Show this endpoint'
+      get '/simple/show' do
+        { foo: 'bar' }
+      end
+
+      desc 'Hide this endpoint', hidden: true
+      get '/simple/hide' do
+        { foo: 'bar' }
+      end
+
+      desc 'Lazily hide endpoint', hidden: -> { true }
+      get '/simple/lazy' do
+        { foo: 'bar' }
+      end
+    end
+
+    class HideNamespaceApi < Grape::API
+      mount HideNamespaceMountedApi
+      add_swagger_documentation
+    end
+  end
+
+  def app
+    HideNamespaceApi
+  end
+
+  it 'retrieves swagger-documentation on /swagger_doc' do
+    get '/swagger_doc.json'
+    expect(JSON.parse(last_response.body)).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/show' => {
+          'get' => {
+            'description' => 'Show this endpoint',
+            'produces' => ['application/json'],
+            'operationId' => 'getSimpleShow',
+            'tags' => ['simple'], 'responses' => { '200' => { 'description' => 'Show this endpoint' } }
+          }
+        }
+      }
+    )
+  end
+
+  it "retrieves the documentation for mounted-api that doesn't include hidden endpoints" do
+    get '/swagger_doc/simple.json'
+    expect(JSON.parse(last_response.body)).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/show' => {
+          'get' => {
+            'description' => 'Show this endpoint',
+            'produces' => ['application/json'],
+            'tags' => ['simple'],
+            'operationId' => 'getSimpleShow',
+            'responses' => { '200' => { 'description' => 'Show this endpoint' } }
+          }
+        }
+      }
+    )
+  end
+end

data/spec/swagger_v2/host_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'host in the swagger_doc' do
+  before :all do
+    module TheApi
+      class EmptyApi < Grape::API
+        format :json
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::EmptyApi
+  end
+
+  describe 'host should include port' do
+    subject do
+      get 'http://example.com:8080/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['host']).to eq 'example.com:8080'
+    end
+  end
+
+  describe 'respect X-Forwarded-Host over Host header' do
+    subject do
+      header 'Host', 'dummy.example.com'
+      header 'X-Forwarded-Host', 'real.example.com'
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['host']).to eq 'real.example.com'
+    end
+  end
+end

data/spec/swagger_v2/inheritance_and_discriminator_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Inheritance and Discriminator' do
+  before :all do
+    module InheritanceTest
+      module Entities
+        # example from https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#models-with-polymorphism-supports
+        class Pet < Grape::Entity
+          expose :type, documentation: {
+            type: 'string',
+            is_discriminator: true,
+            required: true
+          }
+          expose :name, documentation: {
+            type: 'string',
+            required: true
+          }
+        end
+
+        class Cat < Pet
+          expose :huntingSkill, documentation: {
+            type: 'string',
+            description: 'The measured skill for hunting',
+            default: 'lazy',
+            values: %w[
+              clueless
+              lazy
+              adventurous
+              aggressive
+            ]
+          }
+        end
+      end
+
+      class NameApi < Grape::API
+        add_swagger_documentation models: [Entities::Pet, Entities::Cat]
+      end
+    end
+  end
+
+  context 'Parent model' do
+    let(:app) { InheritanceTest::NameApi }
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['definitions']
+    end
+
+    specify do
+      subject['InheritanceTest_Entities_Pet'].key?('discriminator')
+      subject['InheritanceTest_Entities_Pet']['discriminator'] = 'type'
+      subject['InheritanceTest_Entities_Cat'].key?('allOf')
+    end
+  end
+end

data/spec/swagger_v2/mount_override_api_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'mount override api' do
+  def app
+    old_api = Class.new(Grape::API) do
+      desc 'old endpoint', success: { code: 200, message: 'old message' }
+      params do
+        optional :param, type: Integer, desc: 'old param'
+      end
+      get do
+        'old'
+      end
+    end
+
+    new_api = Class.new(Grape::API) do
+      desc 'new endpoint', success: { code: 200, message: 'new message' }
+      params do
+        optional :param, type: String, desc: 'new param'
+      end
+      get do
+        'new'
+      end
+    end
+
+    Class.new(Grape::API) do
+      mount new_api
+      mount old_api
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  context 'actual api request' do
+    subject do
+      get '/'
+      last_response.body
+    end
+
+    it 'returns data from new endpoint' do
+      is_expected.to eq 'new'
+    end
+  end
+
+  context 'api documentation' do
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)['paths']['/']['get']
+    end
+
+    it 'shows documentation from new endpoint' do
+      expect(subject['parameters'][0]['description']).to eql('new param')
+      expect(subject['parameters'][0]['type']).to eql('string')
+      expect(subject['responses']['200']['description']).to eql('new message')
+    end
+  end
+end

data/spec/swagger_v2/mounted_target_class_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+xdescribe 'docs mounted separately from api' do
+  before :all do
+    class ActualApi < Grape::API
+      desc 'Document root'
+
+      desc 'This gets something.',
+           notes: '_test_'
+      get '/simple' do
+        { bla: 'something' }
+      end
+    end
+
+    class MountedDocs < Grape::API
+      add_swagger_documentation(target_class: ActualApi)
+    end
+
+    class WholeApp < Grape::API
+      mount ActualApi
+      mount MountedDocs
+    end
+  end
+
+  def app
+    WholeApp
+  end
+
+  it 'retrieves docs for actual api class' do
+    get '/swagger_doc.json'
+    expect(JSON.parse(last_response.body)).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'],
+            'responses' => { '200' => { 'description' => 'This gets something.' } },
+            'tags' => ['simple'],
+            'operationId' => 'getSimple'
+          }
+        }
+      }
+    )
+  end
+
+  it 'retrieves docs for endpoint in actual api class' do
+    get '/swagger_doc/simple.json'
+    expect(JSON.parse(last_response.body)).to eq(
+      'info' => { 'title' => 'API title', 'version' => '0.0.1' },
+      'swagger' => '2.0',
+      'tags' => [{ 'name' => 'simple', 'description' => 'Operations about simples' }],
+      'produces' => ['application/xml', 'application/json', 'application/octet-stream', 'text/plain'],
+      'host' => 'example.org',
+      'paths' => {
+        '/simple' => {
+          'get' => {
+            'description' => 'This gets something.',
+            'produces' => ['application/json'],
+            'responses' => {
+              '200' => { 'description' => 'This gets something.' }
+            },
+            'tags' => ['simple'],
+            'operationId' => 'getSimple'
+          }
+        }
+      }
+    )
+  end
+end