gitlab-grape-openapi 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79aec4f1d4657df18a7ccbcf6b689c9f00f8f0b5c940d508da34b05112aa8432
-  data.tar.gz: 275e4524ae0d61929af41ca0540ff080f49790f0a2cbb1308f4a0e6d6b79f75f
+  metadata.gz: 3c0d95f2bff47a6ef1c1c9d251b48b4e12748f8348b112a408cf94c97d62b6d3
+  data.tar.gz: 166affd62ad738cdd13b2c414bb131fd9065506c18b3dee7e32dc861ad23e3fd
 SHA512:
-  metadata.gz: cd0dfaa149fb09c6a61bd2b8c9256d506e6bc62da716faed13e9b0c2f48932efed53b69315c330d1f91f8bf550bb5728fc284865748966b39f15b4a7d7598c67
-  data.tar.gz: c937af8a3e5f1a4f80ae412e7d444f1b11c7d30268b5c64dd9441c3e2b6125db1b325387effa1ec917821211ee12ca7e140dd1f9e659bcab039c86d99c3e3db4
+  metadata.gz: a8695acf55cddb13dc6ad5078a2ea7fca4e251abe152f9c45b9457018bc47eda0708ff7a9e018713cf6ba6ac77532d65368a31112cc4cb1d4b61a9be9d1c9f80
+  data.tar.gz: 7de023af2bf2810e32513a09b2ea6c2520ea1b1d4a46be61f5ff6acf84637dfe6d1ab922bb51a0b223186f0baa3530ad9b19b229eca8c535e63f3e25c1936ee0

data/README.md

@@ -93,17 +93,17 @@ end
 
 ### Configuration Options
 
-| Option                 | Type                            | Default | Description                                                  |
-| ---------------------- | ------------------------------- | ------- | ------------------------------------------------------------ |
-| `info`                 | `Models::Info`                  | `nil`   | API metadata (title, description, version, terms of service) |
-| `api_prefix`           | `String`                        | `"api"` | URL prefix for API routes                                    |
-| `api_version`          | `String`                        | `"v1"`  | API version string                                           |
-| `servers`              | `Array<Models::Server>`         | `[]`    | Server definitions for the API                               |
-| `security_schemes`     | `Array<Models::SecurityScheme>` | `[]`    | Authentication/authorization schemes                         |
-| `excluded_api_classes` | `Array<String>`                 | `[]`    | API class names to exclude from generation                   |
-| `tag_overrides`        | `Hash`                          | `{}`    | Map of tag names to their display overrides                  |
-| `annotations`          | `Hash`                          | `{}`    | Map of Grape route settings to OpenAPI extension names       |
-| `warnings`             | `Boolean`                       | `false` | Emit stderr warnings for synthesized (undeclared) path params |
+| Option                 | Type                            | Default | Description                                                      |
+| ---------------------- | ------------------------------- | ------- | ---------------------------------------------------------------- |
+| `info`                 | `Models::Info`                  | `nil`   | API metadata (title, description, version, terms of service)     |
+| `api_prefix`           | `String`                        | `"api"` | URL prefix for API routes                                        |
+| `api_version`          | `String`                        | `"v1"`  | API version string                                               |
+| `servers`              | `Array<Models::Server>`         | `[]`    | Server definitions for the API                                   |
+| `security_schemes`     | `Array<Models::SecurityScheme>` | `[]`    | Authentication/authorization schemes                             |
+| `excluded_api_classes` | `Array<String>`                 | `[]`    | API class names to exclude from generation                       |
+| `tag_overrides`        | `Hash`                          | `{}`    | Map of tag names to their display overrides                      |
+| `annotations`          | `Hash`                          | `{}`    | Map of Grape route settings to OpenAPI extension names           |
+| `warnings`             | `Boolean`                       | `false` | Emit stderr warnings for synthesized params, skipped constraints |
 
 ### Annotations
 
@@ -185,15 +185,87 @@ Generator
 │   ├── ParameterConverter  - Converts endpoint parameters
 │   ├── ResponseConverter   - Converts endpoint responses
 │   └── RequestBodyConverter - Converts request bodies
-└── TypeResolver        - Maps Ruby/Grape types to OpenAPI types
+├── MediaTypeResolver   - Maps declared media types to response schemas
+├── TypeResolver        - Maps Ruby/Grape types to OpenAPI types
+└── CrossFieldValidationResolver - Documents Grape cross-field validations in descriptions
 ```
 
+### Parameter constraints
+
+The gem documents Grape's `mutually_exclusive` param constraint by appending a
+note such as ``Mutually exclusive with `author_username`.`` to each affected
+parameter's (or request-body property's) `description` — for both query/path
+params (`GET`/`DELETE`) and request-body params (`POST`/`PUT`/`PATCH`).
+
+OpenAPI 3.0 has no cross-parameter constraint keyword, and the target renderer
+(Scalar) does not render JSON Schema `not`/`allOf`, so the constraint is stated
+in prose; Grape enforces it at runtime (HTTP 400). A param appearing in several
+declarations lists every partner in its note.
+
+The gem reads the validation stack through `grape_compat`, so this works on both
+Grape 2.4 and 3.2. Each group is keyed by the full bracketed param path
+(`not[author_id]`) rather than the bare name. Because Grape flattens every nested
+param into the route's query params, a constraint nested inside a `Hash` *query*
+filter is documented the same as a top-level one. A constraint nested inside a
+request-body object property has no top-level property to attach to and is
+skipped; when `warnings` is enabled the gem logs one line per skipped group so it
+is visible in source. The sibling constraints (`exactly_one_of`,
+`at_least_one_of`, `all_or_none_of`) are not yet supported.
+
 ### Registries
 
 - **SchemaRegistry** - Tracks converted entity schemas
 - **RequestBodyRegistry** - Tracks request body schemas
 - **TagRegistry** - Tracks API tags
 
+### Response media types
+
+Responses default to `application/json`, described by the `$ref` of the entity
+declared with `success` / `entity`. Endpoints that return a file or plain text
+instead declare their media type with `produces` in the `desc` block:
+
+```ruby
+desc 'Download an export' do
+  produces %w[application/octet-stream]
+  success code: 200
+end
+get ':id/export/download' do
+  # ...
+end
+```
+
+which becomes:
+
+```yaml
+'200':
+  description: OK
+  content:
+    application/octet-stream:
+      schema:
+        type: string
+        format: binary
+```
+
+`produces` accepts a bare String as well as an Array, and each declared type
+gets its own entry in `content`. The mapping is:
+
+| Declared media type | Emitted schema |
+| ------------------- | -------------- |
+| `application/octet-stream`, `application/gzip`, `application/x-tar` | `{ type: string, format: binary }` |
+| `text/*`, `application/yaml` | `{ type: string }` |
+| `application/json` | none — the entity `$ref` describes it |
+
+A type outside this table is **skipped** rather than guessed at, since assuming
+"binary" would misdescribe a structured payload such as `application/xml`. The
+response keeps its bare shape, so a new media type needs adding to
+`MediaTypeResolver` before it appears in the spec.
+
+`produces` only affects the success response; failure responses stay JSON.
+
+A route that declares `success File` (with no `produces`) is treated as
+`application/octet-stream`, matching `grape-swagger`. An explicit `produces`
+takes precedence, so it can override that inference.
+
 ### Optional path segments
 
 Grape lets a route mark a path segment as optional with parentheses, e.g.

data/lib/gitlab/grape_openapi/concerns/constraint_applier.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Applies the `values:` and `default:` parameter constraints to an already-built schema.
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module ConstraintApplier
+        include Serializable
+
+        private
+
+        # values: on an array-typed parameter constrains each element, so it belongs
+        # on items.enum rather than on the array schema itself.
+        def apply_array_enum!(schema, values)
+          return unless schema[:type] == 'array' && schema[:items].is_a?(Hash)
+          return unless values.is_a?(Array)
+
+          schema[:items][:enum] = values
+        end
+
+        def apply_default!(schema, default, example: nil)
+          return if default.nil?
+
+          members = schema[:oneOf] || schema[:anyOf]
+          return apply_union_default!(members, default) if members
+
+          value = resolve_default(default, example: example)
+          schema[:default] = value unless value.nil?
+        end
+
+        # `example` is unused here; ParameterConverter overrides this to feed it to its time serializer.
+        def resolve_default(default, example: nil) # rubocop:disable Lint/UnusedMethodArgument -- overridden
+          return unless serializable?(default)
+
+          default
+        end
+
+        # When a union (oneOf) schema has a `default:`, attach it to every member
+        # whose schema can accept the default value. For arrays this includes
+        # checking the items type so `[1, 2]` lands on `items: { type: integer }`
+        # but not on `items: { type: string }`. Empty arrays are type-agnostic
+        # and attach to all array members.
+        def apply_union_default!(members, default)
+          return unless serializable?(default)
+
+          members.each do |member|
+            member[:default] = default if member_accepts_default?(member, default)
+          end
+        end
+
+        def member_accepts_default?(member, default)
+          case member[:type]
+          when 'integer' then default.is_a?(Integer)
+          when 'number'  then default.is_a?(Numeric)
+          when 'boolean' then [true, false].include?(default)
+          when 'string'  then default.is_a?(String) || default.is_a?(Symbol)
+          when 'array'   then array_member_accepts?(member, default)
+          when 'object'  then default.is_a?(Hash)
+          end
+        end
+
+        def array_member_accepts?(member, default)
+          return false unless default.is_a?(Array)
+          return true if default.empty?
+
+          item_type = member.dig(:items, :type)
+          default.all? { |element| openapi_type_accepts?(item_type, element) }
+        end
+
+        def openapi_type_accepts?(openapi_type, value)
+          case openapi_type
+          when 'integer' then value.is_a?(Integer)
+          when 'number'  then value.is_a?(Numeric)
+          when 'boolean' then [true, false].include?(value)
+          when 'string'  then value.is_a?(String) || value.is_a?(Symbol)
+          else true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/concerns/nullability.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Determines whether a param is nullable.
+#
+# Grape default behaviour sets nullability true for plain params.
+# Two declarations remove it: a `default:`, which Grape's
+# DefaultValidator substitutes for the null before the endpoint runs, and a path
+# parameter, which is a required URL segment.
+#
+# The `minLength: 1` branch is mutually exclusive with nullability and stays coupled
+# here deliberately: applying the two independently would mark every required enum
+# nullable.
+#
+# NOTE: `param_options[:allow_blank]` is always nil. Grape omits allow_blank from
+# route.params, so that clause is dead and only `required && values` fires.
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module Nullability
+        private
+
+        def apply_nullability!(schema, param_options, in_value: nil)
+          if blank_rejected?(param_options)
+            schema[:minLength] = 1 if schema[:type] == 'string'
+          elsif nullable?(param_options, in_value)
+            mark_nullable!(schema)
+          end
+        end
+
+        def blank_rejected?(param_options)
+          param_options[:allow_blank] == false ||
+            (param_options[:required] && param_options[:values])
+        end
+
+        def nullable?(param_options, in_value)
+          return false if in_value == 'path'
+
+          param_options[:default].nil?
+        end
+
+        # Grape substitutes the default regardless of which union member matched, so
+        # nullability applies to every member or none.
+        def mark_nullable!(schema)
+          members = schema[:oneOf] || schema[:anyOf]
+          return members.each { |member| member[:nullable] = true } if members
+
+          schema[:nullable] = true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Documents Grape cross-field param validations by appending a note to each
+# affected parameter's / request-body property's description.
+#
+# OpenAPI 3.0 has no cross-parameter keyword and Scalar (the renderer) does not
+# render JSON Schema `not`/`allOf`, so these constraints are stated in prose;
+# Grape enforces them at runtime (HTTP 400).
+#
+# Each cross-field validator is a CONSTRAINTS entry pairing the validator class
+# names it carries across supported Grape versions (Grape 3.2 renamed several)
+# with a note strategy. A strategy receives every group of its kind found on the
+# route (each group an array of top-level attribute-name strings) and returns
+# `{ param => note }`.
+#
+# The validations read and the Grape 2.x/3.2 shape difference are isolated in
+# GrapeCompat.
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      class CrossFieldValidationResolver
+        MUTUALLY_EXCLUSIVE = {
+          classes: [
+            'Grape::Validations::Validators::MutualExclusionValidator',  # Grape < 3.2
+            'Grape::Validations::Validators::MutuallyExclusiveValidator' # Grape >= 3.2
+          ].freeze,
+          notes: lambda do |groups|
+            partners = Hash.new { |hash, key| hash[key] = [] }
+
+            groups.each do |group|
+              group.each do |name|
+                (group - [name]).each do |other|
+                  partners[name] << other unless partners[name].include?(other)
+                end
+              end
+            end
+
+            partners.transform_values do |others|
+              "Mutually exclusive with #{others.map { |name| "`#{name}`" }.join(', ')}."
+            end
+          end
+        }.freeze
+
+        CONSTRAINTS = [MUTUALLY_EXCLUSIVE].freeze
+
+        # For callers that need notes alone, which is every caller that has no
+        # nested scope to skip - see `#notes`.
+        def self.notes_for(route, attributes)
+          new(route, attributes).notes
+        end
+
+        # Appends a note to an existing description so the two read as separate
+        # sentences. Returns the note alone when there is no
+        # existing text.
+        def self.append_note(description, note)
+          text = description.to_s.strip
+          return note if text.empty?
+
+          text += '.' unless text.end_with?('.', '!', '?')
+          "#{text} #{note}"
+        end
+
+        # `attributes` are the param names the caller is able to annotate: a
+        # route's query params, or a request body's top-level properties. Both
+        # readers below share one walk of the route's validations, so a caller
+        # that needs both pays for it once.
+        def initialize(route, attributes)
+          @route = route
+          @attributes = attributes
+        end
+
+        # Per-param description notes for every cross-field constraint on the
+        # route, e.g. { 'files' => 'Mutually exclusive with `content`.' }.
+        # Notes from different constraints on the same param are
+        # joined. Returns {} when there are none.
+        def notes
+          @notes ||= matched_entries.each_with_object({}) do |(constraint, entries), result|
+            groups = annotatable_groups(entries)
+            next if groups.empty?
+
+            constraint[:notes].call(groups).each do |param, note|
+              result[param] = self.class.append_note(result[param], note)
+            end
+          end
+        end
+
+        # The groups `notes` could NOT annotate (a member isn't one of `attributes`).
+        def skipped
+          @skipped ||= matched_entries.flat_map do |_constraint, entries|
+            constrained_groups(entries).reject { |group| fully_known?(group) }
+          end.uniq
+        end
+
+        private
+
+        attr_reader :route, :attributes
+
+        def known_names
+          @known_names ||= Array(attributes).map(&:to_s)
+        end
+
+        # Groups all validations on the route
+        # Returns only validations with classes in CONSTRAINTS:
+        # [[MUTUALLY_EXCLUSIVE, [
+        #  { validator_class: Grape::Validations::Validators::MutualExclusionValidator,
+        #    full_names: ["content", "files"] }
+        #  ]]]
+        def matched_entries
+          @matched_entries ||= begin
+            by_validator = GrapeCompat.all_validations(route).group_by { |entry| validator_name(entry) }
+
+            CONSTRAINTS.map do |constraint|
+              [constraint, by_validator.values_at(*constraint[:classes]).compact.flatten]
+            end
+          end
+        end
+
+        # Groups whose members are all in the known set. The exact complement of
+        # what `skipped` keeps, so both derive from `fully_known?` rather than
+        # restating the condition and risking drift.
+        def annotatable_groups(entries)
+          constrained_groups(entries).select { |group| fully_known?(group) }
+        end
+
+        # Every distinct group a constraint declares. A single-member group
+        # constrains nothing - Grape accepts `mutually_exclusive :a` - so it is
+        # neither annotated nor reported as skipped.
+        def constrained_groups(entries)
+          entries.map { |entry| group_members(entry) }.uniq.select { |group| group.length >= 2 }
+        end
+
+        # Whether the caller can annotate every member of the group.
+        def fully_known?(group)
+          (group - known_names).empty?
+        end
+
+        # eg. => 'Grape::Validations::Validators::MutuallyExclusiveValidator'
+        def validator_name(entry)
+          entry[:validator_class]&.name
+        end
+
+        # Full bracketed paths
+        # top level eg. ["author_id", "author_username"]
+        # nested(nested under `not:`) eg. ["not[author_id]", "not[author_username]"]
+        def group_members(entry)
+          Array(entry[:full_names]).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -175,12 +175,13 @@ module Gitlab
         end
 
         def build_one_of_property(types, documentation, default_value)
-          {
-            oneOf: types.map { |type| build_type_schema(type, documentation) },
+          members = types.map { |type| build_type_schema(type, documentation) }
+
+          TypeResolver.union_schema(members).merge(
             description: documentation[:desc],
             default: default_value,
             example: documentation[:example]
-          }
+          )
         end
 
         def build_single_type_property(type, documentation, default_value)

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      # Maps the media types a route declares via `produces` to the OpenAPI
+      # schema describing that response body.
+      #
+      # Media types the gem cannot describe resolve to `nil` so callers skip
+      # them instead of guessing.
+      class MediaTypeResolver
+        BINARY_SCHEMA = { type: 'string', format: 'binary' }.freeze
+        TEXT_SCHEMA = { type: 'string' }.freeze
+
+        OCTET_STREAM_MEDIA_TYPE = 'application/octet-stream'
+
+        BINARY_MEDIA_TYPES = [
+          'application/gzip',
+          OCTET_STREAM_MEDIA_TYPE,
+          'application/x-tar'
+        ].freeze
+
+        TEXT_MEDIA_TYPES = %w[application/yaml].freeze
+
+        TEXT_PREFIX = 'text/'
+
+        class << self
+          # `produces` accepts a bare String as well as an Array, and a declared
+          # type may carry parameters (`text/csv; charset=utf-8`) which are not
+          # part of an OpenAPI content key.
+          #
+          # Downcased because type and subtype are case-insensitive (RFC 6838),
+          # so the tables below can match on one spelling and the emitted content
+          # key stays canonical.
+          def normalize(declaration)
+            Array(declaration).filter_map do |media_type|
+              normalized = media_type.to_s.split(';').first&.strip&.downcase
+              normalized unless normalized.nil? || normalized.empty?
+            end.uniq
+          end
+
+          # `application/json` is handled by the entity `$ref` path
+          #  unrecognized types return nil rather than guessing the type
+          def schema_for(media_type)
+            return BINARY_SCHEMA if BINARY_MEDIA_TYPES.include?(media_type)
+            return TEXT_SCHEMA if TEXT_MEDIA_TYPES.include?(media_type) || media_type.start_with?(TEXT_PREFIX)
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -77,10 +77,10 @@ module Gitlab
           params = if options[:params].empty?
                      []
                    else
-                     options[:params].filter_map do |key, options|
+                     options[:params].filter_map do |key, param_options|
                        Converters::ParameterConverter.convert(
                          key,
-                         options: options,
+                         options: annotate_constraint(key, param_options),
                          validations: validations_for(key.to_sym),
                          route: route
                        )
@@ -94,6 +94,23 @@ module Gitlab
           params.reject { |param| removed.include?(param.name.to_s) }
         end
 
+        def annotate_constraint(key, param_options)
+          note = cross_field_notes[key.to_s]
+          return param_options unless note
+
+          param_options.merge(desc: Converters::CrossFieldValidationResolver.append_note(param_options[:desc], note))
+        end
+
+        # Per-param cross-field constraint notes to fold into descriptions, e.g.
+        #   { 'author_id' => 'Mutually exclusive with `author_username`.' }.
+        # Keyed by the full bracketed param name, so a nested-Hash query filter
+        # (`not[author_id]`, which Grape flattens into `options[:params]`) is
+        # annotated the same way a top-level param is.
+        def cross_field_notes
+          @cross_field_notes ||=
+            Converters::CrossFieldValidationResolver.notes_for(route, options[:params].keys.map(&:to_s))
+        end
+
         def inject_missing_path_parameters(params)
           declared_names = params.map(&:name).to_set
 
@@ -214,16 +231,11 @@ module Gitlab
         end
 
         def normalized_path
-          @normalized_path ||= path_override || normalize_path_pattern.gsub('{version}', config.api_version)
+          @normalized_path ||= path_override || normalize_path_pattern
         end
 
         def normalize_path_pattern
-          path = pattern.origin
-          path
-            .gsub(/\(\.:format\)$/, '')
-            .gsub(/[()\\]/, '')
-            .gsub(/:\w+/) { |match| "{#{match[1..]}}" }
-            .gsub('{version}', config.api_version)
+          NormalizedPath.new(pattern.origin).to_display_path(config.api_version)
         end
 
         def camelize(string)