gitlab-grape-swagger 1.5.0

data/lib/grape-swagger.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'grape'
+
+require 'grape-swagger/instance'
+
+require 'grape-swagger/version'
+require 'grape-swagger/endpoint'
+require 'grape-swagger/errors'
+
+require 'grape-swagger/doc_methods'
+require 'grape-swagger/model_parsers'
+
+module GrapeSwagger
+  class << self
+    def model_parsers
+      @model_parsers ||= GrapeSwagger::ModelParsers.new
+    end
+  end
+  autoload :Rake, 'grape-swagger/rake/oapi_tasks'
+end
+
+module SwaggerRouting
+  private
+
+  def combine_routes(app, doc_klass)
+    app.routes.each do |route|
+      route_path = route.path
+      route_match = route_path.split(/^.*?#{route.prefix}/).last
+      next unless route_match
+
+      # want to match emojis … ;)
+      # route_match = route_match
+      #   .match('\/([\p{Alnum}p{Emoji}\-\_]*?)[\.\/\(]') || route_match.match('\/([\p{Alpha}\p{Emoji}\-\_]*)$')
+      route_match = route_match.match('\/([\p{Alnum}\-\_]*?)[\.\/\(]') || route_match.match('\/([\p{Alpha}\-\_]*)$')
+      next unless route_match
+
+      resource = route_match.captures.first
+      resource = '/' if resource.empty?
+      @target_class.combined_routes[resource] ||= []
+      next if doc_klass.hide_documentation_path && route.path.match(/#{doc_klass.mount_path}($|\/|\(\.)/)
+
+      @target_class.combined_routes[resource].unshift route
+    end
+  end
+
+  def determine_namespaced_routes(name, parent_route)
+    if parent_route.nil?
+      @target_class.combined_routes.values.flatten
+    else
+      parent_route.reject do |route|
+        !route_path_start_with?(route, name) || !route_instance_variable_equals?(route, name)
+      end
+    end
+  end
+
+  def combine_namespace_routes(namespaces)
+    # iterate over each single namespace
+    namespaces.each_key do |name, _|
+      # get the parent route for the namespace
+      parent_route_name = extract_parent_route(name)
+      parent_route = @target_class.combined_routes[parent_route_name]
+      # fetch all routes that are within the current namespace
+      namespace_routes = determine_namespaced_routes(name, parent_route)
+
+      # default case when not explicitly specified or nested == true
+      standalone_namespaces = namespaces.reject do |_, ns|
+        !ns.options.key?(:swagger) ||
+          !ns.options[:swagger].key?(:nested) ||
+          ns.options[:swagger][:nested] != false
+      end
+
+      parent_standalone_namespaces = standalone_namespaces.select { |ns_name, _| name.start_with?(ns_name) }
+      # add only to the main route
+      # if the namespace is not within any other namespace appearing as standalone resource
+      # rubocop:disable Style/Next
+      if parent_standalone_namespaces.empty?
+        # default option, append namespace methods to parent route
+        parent_route = @target_class.combined_namespace_routes.key?(parent_route_name)
+        @target_class.combined_namespace_routes[parent_route_name] = [] unless parent_route
+        @target_class.combined_namespace_routes[parent_route_name].push(*namespace_routes)
+      end
+      # rubocop:enable Style/Next
+    end
+  end
+
+  def extract_parent_route(name)
+    route_name = name.match(%r{^/?([^/]*).*$})[1]
+    return route_name unless route_name.include? ':'
+
+    matches = name.match(/\/\p{Alpha}+/)
+    matches.nil? ? route_name : matches[0].delete('/')
+  end
+
+  def route_instance_variable(route)
+    route.instance_variable_get(:@options)[:namespace]
+  end
+
+  def route_instance_variable_equals?(route, name)
+    route_instance_variable(route) == "/#{name}" ||
+      route_instance_variable(route) == "/:version/#{name}"
+  end
+
+  def route_path_start_with?(route, name)
+    route_prefix = route.prefix ? "/#{route.prefix}/#{name}" : "/#{name}"
+    route_versioned_prefix = route.prefix ? "/#{route.prefix}/:version/#{name}" : "/:version/#{name}"
+
+    route.path.start_with?(route_prefix, route_versioned_prefix)
+  end
+end
+
+module SwaggerDocumentationAdder
+  attr_accessor :combined_namespaces, :combined_namespace_identifiers, :combined_routes, :combined_namespace_routes
+
+  include SwaggerRouting
+
+  def add_swagger_documentation(options = {})
+    documentation_class = create_documentation_class
+
+    version_for(options)
+    options = { target_class: self }.merge(options)
+    @target_class = options[:target_class]
+    auth_wrapper = options[:endpoint_auth_wrapper] || Class.new
+
+    use auth_wrapper if auth_wrapper.method_defined?(:before) && !middleware.flatten.include?(auth_wrapper)
+
+    documentation_class.setup(options)
+    mount(documentation_class)
+
+    @target_class.combined_routes = {}
+    combine_routes(@target_class, documentation_class)
+
+    @target_class.combined_namespaces = {}
+    combine_namespaces(@target_class)
+
+    @target_class.combined_namespace_routes = {}
+    @target_class.combined_namespace_identifiers = {}
+    combine_namespace_routes(@target_class.combined_namespaces)
+
+    exclusive_route_keys = @target_class.combined_routes.keys - @target_class.combined_namespaces.keys
+    exclusive_route_keys.each do |key|
+      @target_class.combined_namespace_routes[key] = @target_class.combined_routes[key]
+    end
+    documentation_class
+  end
+
+  private
+
+  def version_for(options)
+    options[:version] = version if version
+  end
+
+  def combine_namespaces(app)
+    app.endpoints.each do |endpoint|
+      ns = endpoint.namespace_stackable(:namespace).last
+
+      # use the full namespace here (not the latest level only)
+      # and strip leading slash
+      mount_path = (endpoint.namespace_stackable(:mount_path) || []).join('/')
+      full_namespace = (mount_path + endpoint.namespace).sub(/\/{2,}/, '/').sub(/^\//, '')
+      @target_class.combined_namespaces[full_namespace] = ns if ns
+
+      combine_namespaces(endpoint.options[:app]) if endpoint.options[:app]
+    end
+  end
+
+  def create_documentation_class
+    Class.new(GrapeInstance) do
+      extend GrapeSwagger::DocMethods
+    end
+  end
+end
+
+GrapeInstance.extend(SwaggerDocumentationAdder)

data/spec/issues/267_nested_namespaces.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'nested namespaces' do
+  let(:app) do
+    Class.new(Grape::API) do
+      route_param :root do
+        resources :apps do
+          route_param :app_id do
+            resource :build do
+              desc 'Builds an application'
+              post do
+                { name: 'Test' }
+              end
+            end
+          end
+        end
+      end
+
+      add_swagger_documentation version: 'v1'
+    end
+  end
+
+  describe 'combined_namespace_routes' do
+    it 'parses root namespace properly' do
+      expect(app.combined_namespace_routes.keys).to include('apps')
+    end
+  end
+
+  describe '#extract_parent_route' do
+    it 'extracts parent for non-namespaced path properly' do
+      expect(app.send(:extract_parent_route, '/apps/:app_id/build')).to eq('apps')
+    end
+
+    it 'extracts parent for namespaced path properly' do
+      expect(app.send(:extract_parent_route, '/:root/apps/:app_id/build')).to eq('apps')
+    end
+  end
+
+  describe 'retrieves swagger-documentation on /swagger_doc' do
+    let(:route_name) { '{root}/apps/{app_id}/build' }
+
+    subject do
+      get '/swagger_doc.json'
+      JSON.parse(last_response.body)
+    end
+
+    context 'paths' do
+      specify do
+        expect(subject['paths'].keys).to include "/#{route_name}"
+      end
+    end
+  end
+end

data/spec/issues/403_versions_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'describing versions' do
+  describe 'nothings given' do
+    def app
+      Class.new(Grape::API) do
+        desc 'no versions given'
+        get '/nothings' do
+          { message: 'hello world …' }
+        end
+
+        add_swagger_documentation format: :json
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['info']['version']).to eql '0.0.1'
+      expect(subject['paths'].keys.first).to eql '/nothings'
+    end
+  end
+
+  describe 'API version given' do
+    def app
+      Class.new(Grape::API) do
+        version 'v2', using: :path
+        desc 'api versions given'
+        get '/api_version' do
+          { message: 'hello world …' }
+        end
+
+        add_swagger_documentation format: :json
+      end
+    end
+
+    subject do
+      get '/v2/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['info']['version']).to eql '0.0.1'
+      expect(subject['paths'].keys.first).to eql '/v2/api_version'
+    end
+  end
+
+  describe 'DOC version given' do
+    def app
+      Class.new(Grape::API) do
+        desc 'doc versions given'
+        get '/doc_version' do
+          { message: 'hello world …' }
+        end
+
+        add_swagger_documentation doc_version: '0.1'
+      end
+    end
+
+    subject do
+      get '/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['info']['version']).to eql '0.1'
+      expect(subject['paths'].keys.first).to eql '/doc_version'
+    end
+  end
+
+  describe 'both versions given' do
+    def app
+      Class.new(Grape::API) do
+        version :v3, using: :path
+        desc 'both versions given'
+        get '/both_versions' do
+          { message: 'hello world …' }
+        end
+
+        add_swagger_documentation doc_version: '0.2'
+      end
+    end
+
+    subject do
+      get '/v3/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['info']['version']).to eql '0.2'
+      expect(subject['paths'].keys.first).to eql '/v3/both_versions'
+    end
+  end
+
+  describe 'try to override grape given version' do
+    def app
+      Class.new(Grape::API) do
+        version :v4, using: :path
+        desc 'overriding grape given version?'
+        get '/grape_version' do
+          { message: 'hello world …' }
+        end
+
+        add_swagger_documentation doc_version: '0.0.3',
+                                  version: 'v5'
+      end
+    end
+
+    subject do
+      get '/v4/swagger_doc'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['info']['version']).to eql '0.0.3'
+      expect(subject['paths'].keys.first).to eql '/v4/grape_version'
+    end
+  end
+end

data/spec/issues/427_entity_as_string_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe '#427 nested entity given as string' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_427 do
+        module Permission
+          class WithoutRole < Grape::Entity
+            expose :id
+            expose :description
+          end
+        end
+
+        class RoleEntity < Grape::Entity
+          expose :id
+          expose :description
+          expose :role
+          expose :permissions, using: 'Permission::WithoutRole'
+        end
+        desc 'Get a list of roles',
+             success: RoleEntity
+        get '/' do
+          present [], with: RoleEntity
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['definitions']
+  end
+
+  specify { expect(subject.keys).to include 'RoleEntity', 'Permission_WithoutRole' }
+end

data/spec/issues/430_entity_definitions_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'definition names' do
+  before :all do
+    module TestDefinition
+      module DummyEntities
+        module WithVeryLongName
+          module AnotherGroupingModule
+            class Class1
+              class Entity < Grape::Entity
+                expose :first_thing
+              end
+            end
+
+            class Class2
+              class Entities < Grape::Entity
+                expose :second_thing
+              end
+            end
+
+            class Class3
+              class Entity < Grape::Entity
+                expose :third_thing
+
+                def self.entity_name
+                  'FooKlass'
+                end
+              end
+            end
+
+            class Class4
+              class FourthEntity < Grape::Entity
+                expose :fourth_thing
+              end
+            end
+
+            class Class5
+              class FithEntity < Class4::FourthEntity
+                expose :fith_thing
+              end
+            end
+
+            class Class6
+              class SixthEntity < Grape::Entity
+                expose :sixth_thing
+
+                def self.entity_name
+                  'BarKlass'
+                end
+              end
+            end
+
+            class Class7
+              class SeventhEntity < Class6::SixthEntity
+                expose :seventh_thing
+
+                private_class_method :entity_name
+              end
+            end
+          end
+        end
+      end
+
+      class NameApi < Grape::API
+        add_swagger_documentation models: [
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class1::Entity,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class2::Entities,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class3::Entity,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class4::FourthEntity,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class5::FithEntity,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class6::SixthEntity,
+          DummyEntities::WithVeryLongName::AnotherGroupingModule::Class7::SeventhEntity
+        ]
+      end
+    end
+  end
+
+  let(:app) { TestDefinition::NameApi }
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['definitions']
+  end
+
+  specify { expect(subject).to include 'TestDefinition_DummyEntities_WithVeryLongName_AnotherGroupingModule_Class1' }
+  specify { expect(subject).to include 'TestDefinition_DummyEntities_WithVeryLongName_AnotherGroupingModule_Class2' }
+  specify { expect(subject).to include 'FooKlass' }
+  specify { expect(subject).to include 'TestDefinition_DummyEntities_WithVeryLongName_AnotherGroupingModule_Class4_FourthEntity' }
+  specify { expect(subject).to include 'TestDefinition_DummyEntities_WithVeryLongName_AnotherGroupingModule_Class5_FithEntity' }
+  specify { expect(subject).to include 'BarKlass' }
+  specify { expect(subject).to include 'TestDefinition_DummyEntities_WithVeryLongName_AnotherGroupingModule_Class7_SeventhEntity' }
+end

data/spec/issues/532_allow_custom_format_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe '#532 allow custom format' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_532 do
+        desc 'issue_532' do
+          consumes ['application/x-www-form-urlencoded']
+        end
+
+        params do
+          requires :logs, type: String, documentation: { format: 'log' }
+          optional :phone_number, type: Integer, documentation: { format: 'phone_number' }
+        end
+
+        post do
+          present params
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  let(:parameters) { subject['paths']['/issue_532']['post']['parameters'] }
+
+  specify do
+    expect(parameters).to eql(
+      [
+        { 'in' => 'formData', 'name' => 'logs', 'type' => 'string', 'format' => 'log', 'required' => true },
+        { 'in' => 'formData', 'name' => 'phone_number', 'type' => 'integer', 'format' => 'phone_number', 'required' => false }
+      ]
+    )
+  end
+end

data/spec/issues/533_specify_status_code_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe '#533 specify status codes' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_533 do
+        desc 'Get a list of stuff',
+             success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+        get do
+          status 202
+          { foo: 'that is the response' }
+        end
+
+        desc 'Post some stuff',
+             success: { code: 202, model: Entities::UseResponse, message: 'a changed status code' }
+        post do
+          status 202
+          { foo: 'that is the response' }
+        end
+
+        desc 'Post some stuff',
+             success: { code: 204, message: 'a changed status code' }
+        patch do
+          status 204
+        end
+
+        desc 'Delete some stuff',
+             success: { code: 203 }
+        delete do
+          status 203
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)['paths']['/issue_533']
+  end
+
+  let(:get_response) { get '/issue_533' }
+  specify { expect(get_response.status).to eql 202 }
+  let(:get_response_documentation) { subject['get']['responses'] }
+  specify do
+    expect(get_response_documentation.keys.first).to eql '202'
+    expect(get_response_documentation['202']).to include 'schema'
+  end
+
+  let(:post_response) { post '/issue_533' }
+  specify { expect(post_response.status).to eql 202 }
+  let(:post_response_documentation) { subject['post']['responses'] }
+  specify do
+    expect(post_response_documentation.keys.first).to eql '202'
+    expect(post_response_documentation['202']).to include 'schema'
+  end
+
+  let(:patch_response) { patch '/issue_533' }
+  specify { expect(patch_response.status).to eql 204 }
+  let(:patch_response_documentation) { subject['patch']['responses'] }
+  specify do
+    expect(patch_response_documentation.keys.first).to eql '204'
+    expect(patch_response_documentation['204']).not_to include 'schema'
+  end
+
+  let(:delete_response) { delete '/issue_533' }
+  specify { expect(delete_response.status).to eql 203 }
+  let(:delete_response_documentation) { subject['delete']['responses'] }
+  specify do
+    expect(delete_response_documentation.keys.first).to eql '203'
+    expect(delete_response_documentation['203']).not_to include 'schema'
+  end
+end

data/spec/issues/537_enum_values_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe '#537 enum values spec' do
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_537 do
+        class Spec < Grape::Entity
+          expose :enum_property, documentation: { values: %i[foo bar] }
+          expose :enum_property_default, documentation: { values: %w[a b c], default: 'c' }
+          expose :own_format, documentation: { format: 'log' }
+        end
+
+        desc 'create account',
+             success: Spec
+        get do
+          { message: 'hi' }
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  let(:property) { subject['definitions']['Spec']['properties']['enum_property'] }
+  specify do
+    expect(property).to include 'enum'
+    expect(property['enum']).to eql %w[foo bar]
+  end
+
+  let(:property_default) { subject['definitions']['Spec']['properties']['enum_property_default'] }
+  specify do
+    expect(property_default).to include 'enum'
+    expect(property_default['enum']).to eql %w[a b c]
+    expect(property_default).to include 'default'
+    expect(property_default['default']).to eql 'c'
+  end
+
+  let(:own_format) { subject['definitions']['Spec']['properties']['own_format'] }
+  specify do
+    expect(own_format).to include 'format'
+    expect(own_format['format']).to eql 'log'
+  end
+end