gitlab-grape-swagger 1.5.0

data/lib/grape-swagger/doc_methods/parse_params.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class ParseParams
+      class << self
+        def call(param, settings, path, route, definitions, consumes)
+          method = route.request_method
+          additional_documentation = settings.fetch(:documentation, {})
+          settings.merge!(additional_documentation)
+          data_type = DataType.call(settings)
+
+          value_type = settings.merge(data_type: data_type, path: path, param_name: param, method: method)
+
+          # required properties
+          @parsed_param = {
+            in: param_type(value_type, consumes),
+            name: settings[:full_name] || param
+          }
+
+          # optional properties
+          document_description(settings)
+          document_type_and_format(settings, data_type)
+          document_array_param(value_type, definitions, consumes) if value_type[:is_array]
+          document_default_value(settings) unless value_type[:is_array]
+          document_range_values(settings) unless value_type[:is_array]
+          document_required(settings)
+          document_additional_properties(definitions, settings) unless value_type[:is_array]
+          document_add_extensions(settings)
+          document_example(settings) if @parsed_param[:in] == 'body'
+
+          @parsed_param
+        end
+
+        private
+
+        def document_description(settings)
+          description = settings[:desc] || settings[:description]
+          @parsed_param[:description] = description if description
+        end
+
+        def document_required(settings)
+          @parsed_param[:required] = settings[:required] || false
+          @parsed_param[:required] = true if @parsed_param[:in] == 'path'
+        end
+
+        def document_range_values(settings)
+          values               = settings[:values] || nil
+          enum_or_range_values = parse_enum_or_range_values(values)
+          @parsed_param.merge!(enum_or_range_values) if enum_or_range_values
+        end
+
+        def document_default_value(settings)
+          @parsed_param[:default] = settings[:default] if settings.key?(:default)
+        end
+
+        def document_type_and_format(settings, data_type)
+          if DataType.primitive?(data_type)
+            data = DataType.mapping(data_type)
+            @parsed_param[:type], @parsed_param[:format] = data
+          else
+            @parsed_param[:type] = data_type
+          end
+          @parsed_param[:format] = settings[:format] if settings[:format].present?
+        end
+
+        def document_add_extensions(settings)
+          GrapeSwagger::DocMethods::Extensions.add_extensions_to_root(settings, @parsed_param)
+        end
+
+        def document_array_param(value_type, definitions, consumes)
+          if value_type[:documentation].present?
+            param_type = value_type[:documentation][:param_type]
+            doc_type = value_type[:documentation][:type]
+            type = DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
+            collection_format = value_type[:documentation][:collectionFormat]
+          end
+
+          array_items = parse_array_item(
+            definitions,
+            type,
+            value_type
+          )
+
+          @parsed_param[:in] = array_param_type(value_type, consumes)
+          @parsed_param[:items] = array_items
+          @parsed_param[:type] = 'array'
+          @parsed_param[:collectionFormat] = collection_format if DataType.collections.include?(collection_format)
+        end
+
+        def array_param_type(value_type, consumes)
+          param_type = value_type[:param_type] || value_type[:in]
+          if param_type
+            param_type
+          elsif %w[POST PUT PATCH].include?(value_type[:method])
+            consumes.include?('application/x-www-form-urlencoded') || consumes.include?('multipart/form-data') ? 'formData' : 'body'
+          elsif DataType.query_array_primitive?(value_type[:data_type])
+            'query'
+          else
+            'formData'
+          end
+        end
+
+        def parse_array_item(definitions, type, value_type)
+          array_items = {}
+          if definitions[value_type[:data_type]]
+            array_items['$ref'] = "#/definitions/#{@parsed_param[:type]}"
+          else
+            array_items[:type] = type || @parsed_param[:type] == 'array' ? 'string' : @parsed_param[:type]
+          end
+          array_items[:format] = @parsed_param.delete(:format) if @parsed_param[:format]
+
+          values = value_type[:values] || nil
+          enum_or_range_values = parse_enum_or_range_values(values)
+          array_items.merge!(enum_or_range_values) if enum_or_range_values
+
+          array_items[:default] = value_type[:default] if value_type[:default].present?
+
+          set_additional_properties, additional_properties = parse_additional_properties(definitions, value_type)
+          array_items[:additionalProperties] = additional_properties if set_additional_properties
+
+          array_items
+        end
+
+        def document_additional_properties(definitions, settings)
+          set_additional_properties, additional_properties = parse_additional_properties(definitions, settings)
+          @parsed_param[:additionalProperties] = additional_properties if set_additional_properties
+        end
+
+        def parse_additional_properties(definitions, settings)
+          return false unless settings.key?(:additionalProperties) || settings.key?(:additional_properties)
+
+          value =
+            if settings.key?(:additionalProperties)
+              GrapeSwagger::Errors::SwaggerSpecDeprecated.tell!(:additionalProperties)
+              settings[:additionalProperties]
+            else
+              settings[:additional_properties]
+            end
+
+          parsed_value =
+            if definitions[value.to_s]
+              { '$ref': "#/definitions/#{value}" }
+            elsif value.is_a?(Class)
+              { type: DataType.call(value) }
+            else
+              value
+            end
+
+          [true, parsed_value]
+        end
+
+        def document_example(settings)
+          example = settings[:example]
+          @parsed_param[:example] = example if example
+        end
+
+        def param_type(value_type, consumes)
+          param_type = value_type[:param_type] || value_type[:in]
+          if value_type[:path].include?("{#{value_type[:param_name]}}")
+            'path'
+          elsif param_type
+            param_type
+          elsif %w[POST PUT PATCH].include?(value_type[:method])
+            consumes.include?('application/x-www-form-urlencoded') || consumes.include?('multipart/form-data') ? 'formData' : 'body'
+          else
+            'query'
+          end
+        end
+
+        def parse_enum_or_range_values(values)
+          case values
+          when Proc
+            parse_enum_or_range_values(values.call) if values.parameters.empty?
+          when Range
+            parse_range_values(values) if values.first.is_a?(Integer)
+          when Array
+            { enum: values }
+          else
+            { enum: [values] } if values
+          end
+        end
+
+        def parse_range_values(values)
+          { minimum: values.first, maximum: values.last }
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/path_string.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class PathString
+      class << self
+        def build(route, path, options = {})
+          # always removing format
+          path.sub!(/\(\.\w+?\)$/, '')
+          path.sub!('(.:format)', '')
+
+          # ... format path params
+          path.gsub!(/:(\w+)/, '{\1}')
+          path.gsub!(/\*(\w+)/, '{\1}')
+
+          # set item from path, this could be used for the definitions object
+          path_name = path.gsub(%r{/{(.+?)}}, '').split('/').last
+          item = path_name.present? ? path_name.singularize.underscore.camelize : 'Item'
+
+          if route.version && options[:add_version]
+            version = GrapeSwagger::DocMethods::Version.get(route)
+            version = version.first while version.is_a?(Array)
+            path.sub!('{version}', version.to_s)
+          else
+            path.sub!('/{version}', '')
+          end
+
+          path = "#{OptionalObject.build(:base_path, options)}#{path}" if options[:add_base_path]
+
+          [item, path.start_with?('/') ? path : "/#{path}"]
+        end
+
+        def generate_optional_segments(path)
+          # always removing format
+          path.sub!(/\(\.\w+?\)$/, '')
+          path.sub!('(.:format)', '')
+
+          paths = []
+          if path.match(/\(.+\)/)
+            # recurse with included optional segment
+            paths.concat(generate_optional_segments(path.sub(/\([^\)]+\)/, '')))
+            # recurse with excluded optional segment
+            paths.concat(generate_optional_segments(path.sub(/\(/, '').sub(/\)/, '')))
+          else
+            paths << path
+          end
+          paths
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/produces_consumes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class ProducesConsumes
+      class << self
+        def call(*args)
+          return ['application/json'] unless args.flatten.present?
+
+          args.flatten.map { |x| Grape::ContentTypes::CONTENT_TYPES[x] || x }.uniq
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/status_codes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class StatusCodes
+      class << self
+        def get
+          {
+            get: { code: 200, message: 'get {item}(s)' },
+            post: { code: 201, message: 'created {item}' },
+            put: { code: 200, message: 'updated {item}' },
+            patch: { code: 200, message: 'patched {item}' },
+            delete: { code: 200, message: 'deleted {item}' },
+            head: { code: 200, message: 'head {item}' },
+            options: { code: 200, message: 'option {item}' }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/tag_name_description.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class TagNameDescription
+      class << self
+        def build(paths)
+          paths.values.each_with_object([]) do |path, memo|
+            tags = path.values.first[:tags]
+            next if tags.nil?
+
+            case tags
+            when String
+              memo << build_memo(tags)
+            when Array
+              path.values.first[:tags].each do |tag|
+                memo << build_memo(tag)
+              end
+            end
+          end.uniq
+        end
+
+        private
+
+        def build_memo(tag)
+          {
+            name: tag,
+            description: "Operations about #{tag.pluralize}"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods/version.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class Version
+      class << self
+        def get(route)
+          version = route.version
+          # for grape version 0.16.2, the version can be a string like '[:v1, :v2]'
+          # for grape version bigger than 0.16.2, the version can be a array like [:v1, :v2]
+          if version.is_a?(String) && version.start_with?('[') && version.end_with?(']')
+            instance_eval(version)
+          else
+            version
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape-swagger/doc_methods.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'grape-swagger/doc_methods/status_codes'
+require 'grape-swagger/doc_methods/produces_consumes'
+require 'grape-swagger/doc_methods/data_type'
+require 'grape-swagger/doc_methods/extensions'
+require 'grape-swagger/doc_methods/format_data'
+require 'grape-swagger/doc_methods/operation_id'
+require 'grape-swagger/doc_methods/optional_object'
+require 'grape-swagger/doc_methods/path_string'
+require 'grape-swagger/doc_methods/tag_name_description'
+require 'grape-swagger/doc_methods/parse_params'
+require 'grape-swagger/doc_methods/move_params'
+require 'grape-swagger/doc_methods/headers'
+require 'grape-swagger/doc_methods/build_model_definition'
+require 'grape-swagger/doc_methods/version'
+require 'grape-swagger/doc_methods/file_params'
+
+module GrapeSwagger
+  module DocMethods
+    DEFAULTS =
+      {
+        info: {},
+        models: [],
+        doc_version: '0.0.1',
+        target_class: nil,
+        mount_path: '/swagger_doc',
+        host: nil,
+        base_path: nil,
+        add_base_path: false,
+        add_version: true,
+        add_root: false,
+        hide_documentation_path: true,
+        format: :json,
+        authorizations: nil,
+        security_definitions: nil,
+        security: nil,
+        api_documentation: { desc: 'Swagger compatible API description' },
+        specific_api_documentation: { desc: 'Swagger compatible API description for specific API' },
+        endpoint_auth_wrapper: nil,
+        swagger_endpoint_guard: nil,
+        token_owner: nil
+      }.freeze
+
+    FORMATTER_METHOD = %i[format default_format default_error_formatter].freeze
+
+    def self.output_path_definitions(combi_routes, endpoint, target_class, options)
+      output = endpoint.swagger_object(
+        target_class,
+        endpoint.request,
+        options
+      )
+
+      paths, definitions   = endpoint.path_and_definition_objects(combi_routes, options)
+      tags                 = tags_from(paths, options)
+
+      output[:tags]        = tags unless tags.empty? || paths.blank?
+      output[:paths]       = paths unless paths.blank?
+      output[:definitions] = definitions unless definitions.blank?
+
+      output
+    end
+
+    def self.tags_from(paths, options)
+      tags = GrapeSwagger::DocMethods::TagNameDescription.build(paths)
+
+      if options[:tags]
+        names = options[:tags].map { |t| t[:name] }
+        tags.reject! { |t| names.include?(t[:name]) }
+        tags += options[:tags]
+      end
+
+      tags
+    end
+
+    def hide_documentation_path
+      @@hide_documentation_path
+    end
+
+    def mount_path
+      @@mount_path
+    end
+
+    def setup(options)
+      options = DEFAULTS.merge(options)
+
+      # options could be set on #add_swagger_documentation call,
+      # for available options see #defaults
+      target_class     = options[:target_class]
+      guard            = options[:swagger_endpoint_guard]
+      api_doc          = options[:api_documentation].dup
+      specific_api_doc = options[:specific_api_documentation].dup
+
+      class_variables_from(options)
+
+      setup_formatter(options[:format])
+
+      desc api_doc.delete(:desc), api_doc
+
+      instance_eval(guard) unless guard.nil?
+
+      get mount_path do
+        header['Access-Control-Allow-Origin']   = '*'
+        header['Access-Control-Request-Method'] = '*'
+
+        GrapeSwagger::DocMethods
+          .output_path_definitions(target_class.combined_namespace_routes, self, target_class, options)
+      end
+
+      desc specific_api_doc.delete(:desc), { params: specific_api_doc.delete(:params) || {}, **specific_api_doc }
+
+      params do
+        requires :name, type: String, desc: 'Resource name of mounted API'
+        optional :locale, type: Symbol, desc: 'Locale of API documentation'
+      end
+
+      instance_eval(guard) unless guard.nil?
+
+      get "#{mount_path}/:name" do
+        I18n.locale = params[:locale] || I18n.default_locale
+
+        combined_routes = target_class.combined_namespace_routes[params[:name]]
+        error!({ error: 'named resource not exist' }, 400) if combined_routes.nil?
+
+        GrapeSwagger::DocMethods
+          .output_path_definitions({ params[:name] => combined_routes }, self, target_class, options)
+      end
+    end
+
+    def class_variables_from(options)
+      @@mount_path              = options[:mount_path]
+      @@class_name              = options[:class_name] || options[:mount_path].delete('/')
+      @@hide_documentation_path = options[:hide_documentation_path]
+    end
+
+    def setup_formatter(formatter)
+      return unless formatter
+
+      FORMATTER_METHOD.each { |method| send(method, formatter) }
+    end
+  end
+end

data/lib/grape-swagger/endpoint/params_parser.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module Endpoint
+    class ParamsParser
+      attr_reader :params, :settings, :endpoint
+
+      def self.parse_request_params(params, settings, endpoint)
+        new(params, settings, endpoint).parse_request_params
+      end
+
+      def initialize(params, settings, endpoint)
+        @params = params
+        @settings = settings
+        @endpoint = endpoint
+      end
+
+      def parse_request_params
+        public_params.each_with_object({}) do |(name, options), memo|
+          name = name.to_s
+          param_type = options[:type]
+          param_type = param_type.to_s unless param_type.nil?
+
+          if param_type_is_array?(param_type)
+            options[:is_array] = true
+            name += '[]' if array_use_braces?
+          end
+
+          memo[name] = options
+        end
+      end
+
+      private
+
+      def array_use_braces?
+        @array_use_braces ||= settings[:array_use_braces] && !includes_body_param?
+      end
+
+      def param_type_is_array?(param_type)
+        return false unless param_type
+        return true if param_type == 'Array'
+
+        param_types = param_type.match(/\[(.*)\]$/)
+        return false unless param_types
+
+        param_types = param_types[0].split(',') if param_types
+        param_types.size == 1
+      end
+
+      def public_params
+        params.select { |param| public_parameter?(param) }
+      end
+
+      def public_parameter?(param)
+        param_options = param.last
+        return true unless param_options.key?(:documentation) && !param_options[:required]
+
+        param_hidden = param_options[:documentation].fetch(:hidden, false)
+        if param_hidden.is_a?(Proc)
+          param_hidden = if settings[:token_owner]
+                           param_hidden.call(endpoint.send(settings[:token_owner].to_sym))
+                         else
+                           param_hidden.call
+                         end
+        end
+        !param_hidden
+      end
+
+      def includes_body_param?
+        params.any? do |_, options|
+          options.dig(:documentation, :param_type) == 'body' || options.dig(:documentation, :in) == 'body'
+        end
+      end
+    end
+  end
+end