gitlab-grape-openapi 0.0.0 → 0.1.1

data/lib/gitlab/grape_openapi/converters/entity_converter.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class EntityConverter
+        attr_reader :entity_class, :schema_registry
+
+        OBJECT_TYPE = 'object'
+        ARRAY_TYPE = 'array'
+        DEFAULT_TYPE = 'string'
+        REF_KEY = '$ref'
+        SCHEMA_PATH_PREFIX = '#/components/schemas/'
+
+        def self.register(entity, schema_registry)
+          case entity
+          when Class
+            return unless grape_entity?(entity)
+
+            new(entity, schema_registry).convert
+          when Hash
+            return unless entity[:model] && grape_entity?(entity[:model])
+
+            new(entity[:model], schema_registry).convert
+          when Array
+            # Array elements may be Class (`success [Entities::Foo]`) or
+            # Hash-with-:model (`success [{ code:, model: Foo }]`). Recurse so
+            # both are registered. Mirrors `ResponseConverter`'s handling.
+            entity.each { |item| register(item, schema_registry) }
+          end
+        end
+
+        def self.grape_entity?(klass)
+          klass.is_a?(Class) && klass.ancestors.include?(Grape::Entity)
+        end
+
+        def initialize(entity_class, schema_registry)
+          @entity_class = entity_class
+          @schema_registry = schema_registry
+        end
+
+        def convert(register: true)
+          normalized_name = schema_registry.normalize_entity_class(entity_class)
+          return schema_registry.schemas[normalized_name] if schema_registry.schemas.key?(normalized_name)
+
+          schema = build_schema
+          schema_registry.register(entity_class, schema) if register
+          schema
+        end
+
+        private
+
+        def build_schema
+          Models::Schema.new.tap do |schema|
+            schema.type = OBJECT_TYPE
+            schema.properties = build_properties
+          end
+        end
+
+        def build_properties
+          root_exposures.each_with_object({}) do |exposure, properties|
+            if inlineable_merge_exposure?(exposure)
+              # `merge: true` flattens the nested entity's exposures into the
+              # parent at runtime. Inline its properties instead of emitting a
+              # `$ref`, so the generated schema reflects the actual response.
+              inline_merged_properties!(properties, exposure)
+            else
+              properties[exposure.key] = build_property(exposure)
+            end
+          end
+        end
+
+        def inlineable_merge_exposure?(exposure)
+          return false unless exposure.for_merge
+
+          nested = nested_entity_class(exposure)
+          nested.is_a?(Class) && self.class.grape_entity?(nested)
+        end
+
+        def inline_merged_properties!(properties, exposure)
+          nested_schema = build_or_fetch_nested_schema(nested_entity_class(exposure))
+          return unless nested_schema&.properties
+
+          # Grape Entity's `merge: true` lets later exposures override earlier
+          # ones with the same key, so merging into `properties` mirrors that.
+          properties.merge!(nested_schema.properties)
+        end
+
+        # Build the merged entity's schema without registering it as a
+        # standalone component. Entities only reached through `merge: true` are
+        # inlined into their parents and do not need their own component entry.
+        # `convert` still returns an already-registered schema when one exists
+        # (for entities also reached via a regular `using:` elsewhere), and
+        # `build_schema` still walks nested `using:` exposures, so any schema
+        # actually referenced by `$ref` remains registered.
+        def build_or_fetch_nested_schema(nested_class)
+          self.class.new(nested_class, schema_registry).convert(register: false)
+        end
+
+        def build_property(exposure)
+          property = extract_basic_attributes(exposure)
+          apply_type_specific_attributes!(property, exposure)
+          property.compact
+        end
+
+        def extract_basic_attributes(exposure)
+          documentation = exposure_documentation(exposure)
+          default_value = exposure_default(exposure)
+
+          type = documentation[:type]
+
+          if multiple_types?(type)
+            build_one_of_property(type, documentation, default_value)
+          else
+            build_single_type_property(type, documentation, default_value)
+          end
+        end
+
+        def multiple_types?(type)
+          type.is_a?(Array) && type.length > 1
+        end
+
+        def build_one_of_property(types, documentation, default_value)
+          {
+            oneOf: types.map { |type| build_type_schema(type, documentation) },
+            description: documentation[:desc],
+            default: default_value,
+            example: documentation[:example]
+          }
+        end
+
+        def build_single_type_property(type, documentation, default_value)
+          # Handle single element arrays
+          actual_type = type.is_a?(Array) ? type.first : type
+
+          {
+            type: TypeResolver.resolve_type(actual_type) || DEFAULT_TYPE,
+            description: documentation[:desc],
+            format: TypeResolver.resolve_format(documentation[:format], actual_type),
+            default: default_value,
+            example: documentation[:example]
+          }
+        end
+
+        def build_type_schema(type, documentation)
+          schema = { type: TypeResolver.resolve_type(type) || DEFAULT_TYPE }
+
+          format = TypeResolver.resolve_format(documentation[:format], type)
+          schema[:format] = format if format
+
+          schema
+        end
+
+        def apply_type_specific_attributes!(property, exposure)
+          # Skip type-specific handling for oneOf properties
+          return if property[:oneOf]
+
+          if array_exposure?(exposure)
+            handle_array_property!(property, exposure)
+          elsif nested_entity?(exposure)
+            handle_entity_reference!(property, exposure)
+          end
+        end
+
+        def handle_array_property!(property, exposure)
+          if nested_entity?(exposure)
+            register_nested_entity(exposure)
+            reference = build_reference(exposure)
+            set_array_property!(property, reference)
+          else
+            set_array_primitive_property!(property)
+          end
+        end
+
+        def handle_entity_reference!(property, exposure)
+          register_nested_entity(exposure)
+          reference = build_reference(exposure)
+          set_reference_property!(property, reference)
+        end
+
+        # Ensure schemas reachable from a route via nested `using:` exposures are
+        # registered too, so dropping the over-broad `Grape::Entity.descendants`
+        # seed in the generator does not leave dangling `$ref`s.
+        def register_nested_entity(exposure)
+          nested = nested_entity_class(exposure)
+          return unless nested.is_a?(Class)
+
+          self.class.register(nested, schema_registry)
+        end
+
+        def set_array_primitive_property!(property)
+          item_type = property[:type] || DEFAULT_TYPE
+          property[:type] = ARRAY_TYPE
+          property[:items] = build_primitive_items(property, item_type)
+        end
+
+        def build_primitive_items(property, item_type)
+          items = { type: item_type }
+
+          # Move format to items if present
+          if property[:format]
+            items[:format] = property[:format]
+            property[:format] = nil
+          end
+
+          items
+        end
+
+        def set_array_property!(property, reference)
+          property[:type] = ARRAY_TYPE
+          property[:items] = { REF_KEY => reference }
+        end
+
+        def set_reference_property!(property, reference)
+          property[:type] = nil
+          property[REF_KEY] = reference
+        end
+
+        def build_reference(exposure)
+          entity_name = nested_entity_class(exposure)
+          "#{SCHEMA_PATH_PREFIX}#{normalize_entity_name(entity_name)}"
+        end
+
+        def normalize_entity_name(entity_name)
+          if entity_name.is_a?(Class)
+            entity_name.name.delete(':')
+          else
+            entity_name.delete(':')
+          end
+        end
+
+        def root_exposures
+          entity_class.root_exposure.nested_exposures
+        end
+
+        def exposure_documentation(exposure)
+          exposure.documentation || {}
+        end
+
+        # Grape Entity stores the `:default` option in `@default_value` but
+        # does not expose a public reader for it. Reaching for the ivar is the
+        # only way to read it without going through `send(:options)`, which the
+        # `GitlabSecurity/PublicSend` rule disallows.
+        def exposure_default(exposure)
+          exposure.instance_variable_get(:@default_value)
+        end
+
+        def nested_entity?(exposure)
+          !nested_entity_class(exposure).nil?
+        end
+
+        # Only `RepresentExposure` instances (i.e. exposures declared with
+        # `using:`) expose a `using_class_name` reader; for any other exposure
+        # type there is no nested entity to reference.
+        def nested_entity_class(exposure)
+          return unless exposure.respond_to?(:using_class_name)
+
+          exposure.using_class_name
+        end
+
+        def array_exposure?(exposure)
+          exposure_documentation(exposure)[:is_array]
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/converters/operation_converter.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class OperationConverter
+        # https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-object
+
+        DASH_SEGMENT = 'Dash'
+
+        def self.convert(route, schema_registry, request_body_registry, inherited_path_params: {})
+          new(
+            route,
+            schema_registry,
+            request_body_registry,
+            inherited_path_params: inherited_path_params
+          ).convert
+        end
+
+        def initialize(route, schema_registry, request_body_registry, inherited_path_params: {})
+          @route = route
+          @schema_registry = schema_registry
+          @request_body_registry = request_body_registry
+          @inherited_path_params = inherited_path_params
+          @config = Gitlab::GrapeOpenapi.configuration
+          @options = route.options
+          @pattern = route.pattern
+          @endpoint = route.app
+        end
+
+        def convert
+          Models::Operation.new.tap do |operation|
+            operation.operation_id = operation_id
+            operation.summary = extract_description
+            operation.description = extract_detail
+            operation.tags = extract_tags
+            operation.deprecated = extract_deprecated
+            operation.hidden = extract_hidden
+            operation.parameters = extract_parameters
+            operation.responses = ResponseConverter.new(@route, @schema_registry).convert
+            operation.request_body = extract_request_body || {}
+            operation.annotations = extract_annotations
+          end
+        end
+
+        private
+
+        attr_reader :config, :route, :options, :pattern, :endpoint, :schema_registry, :request_body_registry,
+          :inherited_path_params
+
+        def route_method
+          @route.request_method
+        end
+
+        def extract_annotations
+          return {} unless options[:settings]
+
+          selected_keys = options[:settings].keys.select do |k|
+            config.annotations.key?(k)
+          end
+
+          selected_keys.to_h do |key|
+            [config.annotations[key], options[:settings][key].to_s]
+          end
+        end
+
+        def extract_parameters
+          params = if options[:params].empty?
+                     []
+                   else
+                     options[:params].filter_map do |key, options|
+                       Converters::ParameterConverter.convert(
+                         key,
+                         options: options,
+                         validations: validations_for(key.to_sym),
+                         route: route
+                       )
+                     end
+                   end
+
+          inject_missing_path_parameters(params)
+        end
+
+        def inject_missing_path_parameters(params)
+          declared_names = params.map(&:name).to_set
+
+          path_placeholders = normalized_path.scan(/\{(\w+)\}/).flatten
+          path_segments = normalized_path.split('/')
+
+          path_placeholders.each do |placeholder|
+            next if declared_names.include?(placeholder)
+
+            inherited = lookup_inherited_param(path_segments, placeholder)
+
+            params << if inherited
+                        ParameterConverter.convert(
+                          placeholder,
+                          options: inherited,
+                          route: route
+                        )
+                      else
+                        # Empty schema because no declaration was found locally or in any
+                        # sibling route's path prefix. Valid OpenAPI 3.0 ("any type") but
+                        # incomplete; report the offender to stderr so callers can fix
+                        # it in source.
+                        report_synthesized_parameter(placeholder)
+                        Models::Parameter.new(
+                          placeholder,
+                          options: { required: true },
+                          schema: {},
+                          in_value: 'path'
+                        )
+                      end
+          end
+
+          params
+        end
+
+        # Emit a one-line stderr warning identifying the route and API
+        # class responsible for a `schema: {}` entry in the generated spec.
+        # Disabled by default and gated behind `config.warnings` so it does
+        # not pollute stderr in callers that treat any warning output as a
+        # failure (e.g. GitLab's `fail_on_warnings` static-analysis wrapper).
+        # The output is grep-friendly: each line starts with the literal
+        # `[gitlab-grape-openapi]` tag and includes the HTTP method, the
+        # full normalized path, the placeholder name, and the API class
+        # name. From the class name, the source file follows GitLab's
+        # autoload conventions (`API::Foo::Bar` -> `lib/api/foo/bar.rb`).
+        def report_synthesized_parameter(placeholder)
+          return unless config.warnings
+
+          api_class = route.app.options[:for] if route.app.respond_to?(:options)
+          warn "[gitlab-grape-openapi] synthesized path param: " \
+            "#{http_method} #{normalized_path} placeholder=:#{placeholder} " \
+            "class=#{api_class || 'unknown'}"
+        end
+
+        # Look up a path-prefix-keyed declaration so mounted child routes
+        # can inherit `requires :id` (etc.) from the parent that mounted them.
+        def lookup_inherited_param(path_segments, placeholder)
+          idx = path_segments.index("{#{placeholder}}")
+          return unless idx
+
+          prefix = path_segments[0..idx].join('/')
+          inherited_path_params[[prefix, placeholder]]
+        end
+
+        def operation_id
+          method = http_method.downcase
+          normalized = normalized_path
+          segments = normalized.split('/').reject(&:empty?)
+
+          parts = segments.filter_map do |seg|
+            next DASH_SEGMENT if seg == '-'
+
+            if seg.include?('{')
+              camelize(seg.gsub(/\{[^}]+\}/) { |m| m[1..-2] })
+            else
+              camelize(seg)
+            end
+          end
+
+          "#{method}#{parts.join}"
+        end
+
+        def extract_description
+          description_from_options = options[:description]
+          return description_from_options[:description] if description_from_options.is_a?(Hash)
+          return description_from_options if description_from_options.is_a?(String)
+
+          return unless endpoint
+
+          description_hash = endpoint.inheritable_setting&.namespace
+          description_hash[:description] if description_hash.is_a?(Hash)
+        end
+
+        def extract_detail
+          options.dig(:settings, :description, :detail)
+        end
+
+        def extract_tags
+          Array(@route.settings.dig(:description, :tags)).map do |tag|
+            Gitlab::GrapeOpenapi::Models::Tag.normalize_tag_name(tag)
+          end
+        end
+
+        def extract_deprecated
+          !!options.dig(:settings, :description, :deprecated)
+        end
+
+        def extract_hidden
+          !!options.dig(:settings, :description, :hidden)
+        end
+
+        def path_segments
+          segments = normalized_path.split('/').reject do |segment|
+            segment.empty? || segment.start_with?('{')
+          end
+
+          segments.reject { |seg| seg == config.api_prefix || seg == config.api_version || seg == '-' }
+        end
+
+        def normalized_path
+          @normalized_path ||= begin
+            path = normalize_path_pattern
+            path.gsub('{version}', config.api_version)
+          end
+        end
+
+        def normalize_path_pattern
+          path = pattern.origin
+          path
+            .gsub(/\(\.:format\)$/, '')
+            .gsub(/[()\\]/, '')
+            .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
+            .gsub('{version}', config.api_version)
+        end
+
+        def camelize(string)
+          string.gsub(/[^a-zA-Z0-9_]/, '_').split('_').reject(&:empty?).map(&:capitalize).join
+        end
+
+        def http_method
+          @route.request_method
+        end
+
+        # Get all validations for a single attribute
+        # Looks something like:
+        # [{:attributes=>[:version_prefix],
+        #   :options=>/^[\d+.]+/,
+        #   :required=>false,
+        #   :params_scope=>#<Grape::Validations::ParamsScope:0x000000016dc35820
+        #   :opts=>{:allow_blank=>nil, :fail_fast=>false},
+        #   :validator_class=>Grape::Validations::Validators::RegexpValidator}]
+        def validations_for(attribute)
+          route
+            .app
+            .inheritable_setting
+            .namespace_stackable
+            .new_values[:validations]
+            &.select { |v| v[:attributes].include?(attribute) }
+        end
+
+        def extract_request_body
+          RequestBodyConverter.convert(
+            route: route,
+            options: options,
+            params: options[:params],
+            request_body_registry: request_body_registry
+          )
+        end
+      end
+    end
+  end
+end