gitlab-grape-openapi 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10a34008541dedbab4063d199bbdb94f2d669d94101be45af1023e362bf8c72f
-  data.tar.gz: ba640eb0b0553149b7776bd53afef9eee0c2cc5316dbb4917c44c2099b138d0e
+  metadata.gz: b864030f21b5380efa37ccb02b953f5c8d07b2f4d2fe90eb66334e155674e2bc
+  data.tar.gz: 37b0f04c277c0b1f1027bdb5f0839f06641a3c6e11fd2e9498cb9a192899914b
 SHA512:
-  metadata.gz: fd55dfbd2de53ec38abfd182f89d2dcbf2f03b916fbde38525dd8566c5984d134b21a9ff112123a7d2d9dbec0fc8077c8bf4a04d40117c902215e4a4cb6eb52b
-  data.tar.gz: 4ece03be3b48a4f4082539446d72ab4ac68b8cd0a022ee125f777c7196dd2aac73b154bc98f1518ac078da6b13b26a80c0a0a4dfabada8f220d461b507202e2c
+  metadata.gz: d7e270e89449c2f1dbdfa2f6acb4bb841abf7bbb25adf064a3f41fbf2a61eb8e9f86f698d8c826cdb111cf19aa6f21269984453913fc53554ce6f7f8eb502ba8
+  data.tar.gz: a6e772a0f79d6d1e010ddddf7a6504a96da9d94c2ad34db08bbf58d80e7bffd8df0364dc09b361c0da5cce3d2b163a2dc24cb5d57604a543926a2c1ddc4ed5fa

data/README.md

@@ -17,6 +17,28 @@
 
 Internal gem for generating [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.0) specifications from [Grape](https://github.com/ruby-grape/grape) API definitions, used by [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) to publish its REST API reference.
 
+## Table of contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Configuration Options](#configuration-options)
+  - [Annotations](#annotations)
+- [Usage](#usage)
+  - [Generating an OpenAPI Specification](#generating-an-openapi-specification)
+  - [Usage with `gitlab-org/gitlab`](#usage-with-gitlab-orggitlab)
+- [Architecture](#architecture)
+  - [Parameter constraints](#parameter-constraints)
+  - [Registries](#registries)
+  - [Response media types](#response-media-types)
+  - [Optional path segments](#optional-path-segments)
+  - [Operation IDs and request body schemas](#operation-ids-and-request-body-schemas)
+- [Development](#development)
+  - [Running Tests](#running-tests)
+  - [Linting](#linting)
+  - [Releasing](#releasing)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Add to your Gemfile:
@@ -44,6 +66,8 @@ Gitlab::GrapeOpenapi.configure do |config|
     version: 'v1',
     terms_of_service: 'https://example.com/terms'
   )
+  # A plain Hash (symbol or string keys) is also accepted and wrapped in Models::Info:
+  # config.info = { title: 'My API', version: 'v1' }
 
   # API path configuration
   config.api_prefix = "api"    # Default: "api"
@@ -103,7 +127,7 @@ end
 
 | Option                 | Type                            | Default | Description                                                      |
 | ---------------------- | ------------------------------- | ------- | ---------------------------------------------------------------- |
-| `info`                 | `Models::Info`                  | `nil`   | API metadata (title, description, version, terms of service)     |
+| `info`                 | `Models::Info` or `Hash`        | `nil`   | **Required.** API metadata (title, description, version, terms of service). `title` and `version` must be present and non-blank (not empty or whitespace-only), otherwise generation raises `Gitlab::GrapeOpenapi::ConfigurationError`. A `Hash` is wrapped in `Models::Info`; any other type also raises `ConfigurationError`. |
 | `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                                   |
@@ -123,6 +147,7 @@ The `annotations` configuration maps Grape route settings to OpenAPI vendor exte
 config.annotations = {
   lifecycle: 'x-gitlab-lifecycle'
 }
+```
 
 When a Grape endpoint has:
 
@@ -205,13 +230,15 @@ Generator
 The gem documents Grape's cross-field param constraints by appending a note 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`). Three constraints are supported:
+(`POST`/`PUT`/`PATCH`). All four of Grape's cross-field constraints are
+supported:
 
 | Grape declaration | Note appended to every member |
 |-------------------|-------------------------------|
 | `mutually_exclusive :author_id, :author_username` | ``Mutually exclusive with `author_username`.`` |
 | `exactly_one_of :project_id, :project_path` | ``Exactly one of `project_id`, `project_path` must be provided.`` |
 | `at_least_one_of :assignee_id, :reviewer_id` | ``At least one of `assignee_id`, `reviewer_id` must be provided.`` |
+| `all_or_none_of :extern_uid, :provider` | ``All or none of `extern_uid`, `provider` must be provided.`` |
 
 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
@@ -241,8 +268,7 @@ 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 remaining sibling constraint (`all_or_none_of`) is not
-yet supported.
+is visible in source.
 
 ### Registries
 
@@ -336,6 +362,17 @@ Generating the combinatorial set of paths for routes with more than one
 param-bearing optional segment is **not** supported: such a route raises
 `Gitlab::GrapeOpenapi::MultipleOptionalSegmentsError`.
 
+### Operation IDs and request body schemas
+
+Operation IDs are derived from the HTTP method and normalized route path. If
+two routes produce the same ID, the later operation receives a numeric suffix
+such as `_2`, keeping IDs unique without renaming unaffected operations.
+
+Inline request bodies are emitted as component schemas named
+`<operationId>Request`. The name is independent of the body shape, so adding or
+changing a field does not rename the generated schema; identical bodies on
+different operations retain their own operation-specific names.
+
 ## Development
 
 ```bash

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

@@ -69,7 +69,15 @@ module Gitlab
           notes: GROUP_SENTENCE.call('At least one of')
         }.freeze
 
-        CONSTRAINTS = [MUTUALLY_EXCLUSIVE, EXACTLY_ONE_OF, AT_LEAST_ONE_OF].freeze
+        ALL_OR_NONE_OF = {
+          classes: [
+            'Grape::Validations::Validators::AllOrNoneOfValidator' # Grape all versions
+          ].freeze,
+          summary_format: '%d related parameters must be provided together, or not at all.',
+          notes: GROUP_SENTENCE.call('All or none of')
+        }.freeze
+
+        CONSTRAINTS = [MUTUALLY_EXCLUSIVE, EXACTLY_ONE_OF, AT_LEAST_ONE_OF, ALL_OR_NONE_OF].freeze
 
         # For callers that need notes alone, which is every caller that has no
         # nested scope to skip - see `#notes`.

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

@@ -10,23 +10,25 @@ module Gitlab
 
         def self.convert(
           route, schema_registry, request_body_registry, inherited_path_params: {},
-          path_override: nil, removed_params: [])
+          path_override: nil, removed_params: [], operation_id_registry: nil)
           new(
             route,
             schema_registry,
             request_body_registry,
             inherited_path_params: inherited_path_params,
             path_override: path_override,
-            removed_params: removed_params
+            removed_params: removed_params,
+            operation_id_registry: operation_id_registry
           ).convert
         end
 
         def initialize(
           route, schema_registry, request_body_registry, inherited_path_params: {},
-          path_override: nil, removed_params: [])
+          path_override: nil, removed_params: [], operation_id_registry: nil)
           @route = route
           @schema_registry = schema_registry
           @request_body_registry = request_body_registry
+          @operation_id_registry = operation_id_registry
           @inherited_path_params = inherited_path_params
           # @path_override and @removed_params are set together when optional-path-segment variants exist
           @path_override = path_override
@@ -38,8 +40,10 @@ module Gitlab
         end
 
         def convert
+          id = operation_id_registry ? operation_id_registry.register(operation_id) : operation_id
+
           Models::Operation.new.tap do |operation|
-            operation.operation_id = operation_id
+            operation.operation_id = id
             operation.summary = extract_description
             operation.description = annotate_oversized_constraints(extract_detail)
             operation.tags = extract_tags
@@ -47,7 +51,7 @@ module Gitlab
             operation.hidden = extract_hidden
             operation.parameters = extract_parameters
             operation.responses = ResponseConverter.new(@route, @schema_registry).convert
-            operation.request_body = extract_request_body || {}
+            operation.request_body = extract_request_body(id) || {}
             operation.annotations = extract_annotations
           end
         end
@@ -55,7 +59,7 @@ module Gitlab
         private
 
         attr_reader :config, :route, :options, :pattern, :endpoint, :schema_registry, :request_body_registry,
-          :inherited_path_params, :path_override, :removed_params
+          :inherited_path_params, :path_override, :removed_params, :operation_id_registry
 
         def route_method
           @route.request_method
@@ -301,12 +305,13 @@ module Gitlab
           GrapeCompat.validations_for(route, attribute)
         end
 
-        def extract_request_body
+        def extract_request_body(id)
           RequestBodyConverter.convert(
             route: route,
             options: options,
             params: options[:params],
-            request_body_registry: request_body_registry
+            request_body_registry: request_body_registry,
+            operation_id: id
           )
         end
       end

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

@@ -31,6 +31,7 @@ module Gitlab
           @routes = routes
           @schema_registry = schema_registry
           @request_body_registry = request_body_registry
+          @operation_id_registry = OperationIdRegistry.new
           @config = Gitlab::GrapeOpenapi.configuration
           @inherited_path_params = {}
         end
@@ -116,15 +117,18 @@ module Gitlab
 
         def build_path_item(routes_for_path, variant)
           path_item = Models::PathItem.new
+          routes_by_method = routes_for_path.group_by { |route| extract_method(route) }
+            .transform_values(&:last)
 
-          routes_for_path.each do |route|
+          routes_by_method.each_value do |route|
             operation = OperationConverter.convert(
               route,
               schema_registry,
               request_body_registry,
               inherited_path_params: inherited_path_params,
               path_override: variant.path_override,
-              removed_params: variant.removed_params
+              removed_params: variant.removed_params,
+              operation_id_registry: @operation_id_registry
             )
             method = extract_method(route)
             path_item.add_operation(method, operation)

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

@@ -9,17 +9,19 @@ module Gitlab
         GET_METHOD = 'GET'
         DELETE_METHOD = 'DELETE'
 
-        attr_reader :route, :options, :params, :request_body_registry
+        attr_reader :route, :options, :params, :request_body_registry, :operation_id
 
-        def self.convert(route:, options:, params:, request_body_registry:)
-          new(route: route, options: options, params: params, request_body_registry: request_body_registry).convert
+        def self.convert(route:, options:, params:, request_body_registry:, operation_id:)
+          new(route: route, options: options, params: params, request_body_registry: request_body_registry,
+            operation_id: operation_id).convert
         end
 
-        def initialize(route:, options:, params:, request_body_registry:)
+        def initialize(route:, options:, params:, request_body_registry:, operation_id:)
           @route = route
           @options = options
           @params = params
           @request_body_registry = request_body_registry
+          @operation_id = operation_id
         end
 
         def convert
@@ -58,7 +60,7 @@ module Gitlab
           }
           schema[:required] = required_params unless required_params.empty?
 
-          schema_ref = request_body_registry.register(schema)
+          schema_ref = request_body_registry.register(schema, name: "#{operation_id}Request")
 
           {
             required: required_params.any?,

data/lib/gitlab/grape_openapi/generator.rb

@@ -15,11 +15,13 @@ module Gitlab
       end
 
       def generate
+        # Resolved before initialize_tags so an invalid config.info fails before any conversion runs.
+        info = openapi_info
         initialize_tags
 
         {
           openapi: '3.0.0',
-          info: Gitlab::GrapeOpenapi.configuration.info.to_h,
+          info: info,
           tags: tag_registry.tags.sort_by { |t| t.fetch(:name, '') },
           servers: Gitlab::GrapeOpenapi.configuration.servers.map(&:to_h),
           paths: paths,
@@ -50,9 +52,37 @@ module Gitlab
 
       private
 
+      def openapi_info
+        hash = configured_info.to_h
+        return hash unless blank?(hash[:title]) || blank?(hash[:version])
+
+        raise ConfigurationError, "config.info must be set with at least a title and version"
+      end
+
+      def configured_info
+        info = Gitlab::GrapeOpenapi.configuration.info
+
+        case info
+        when Models::Info then info
+        when Hash then Models::Info.new(**info.transform_keys(&:to_sym))
+        when nil then Models::Info.new
+        else
+          raise ConfigurationError,
+            "config.info must be a Gitlab::GrapeOpenapi::Models::Info or Hash, got #{info.class}"
+        end
+      end
+
+      def blank?(value)
+        value.to_s.strip.empty?
+      end
+
       def schemas
         entity_schemas = @schema_registry.schemas.transform_values(&:to_h)
         request_body_schemas = @request_body_registry.schemas
+
+        collisions = entity_schemas.keys & request_body_schemas.keys
+        raise ArgumentError, "Schema component name collision: #{collisions.join(', ')}" unless collisions.empty?
+
         entity_schemas.merge(request_body_schemas)
       end
     end

data/lib/gitlab/grape_openapi/operation_id_registry.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    class OperationIdRegistry
+      def initialize
+        @operation_ids = {}
+      end
+
+      def register(candidate)
+        operation_id = candidate
+        suffix = 2
+
+        while @operation_ids.key?(operation_id)
+          operation_id = "#{candidate}_#{suffix}"
+          suffix += 1
+        end
+
+        @operation_ids[operation_id] = true
+        operation_id
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/request_body_registry.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'openssl'
-
 module Gitlab
   module GrapeOpenapi
     class RequestBodyRegistry
@@ -11,47 +9,19 @@ module Gitlab
 
       def initialize
         @schemas = {}
-        @schema_hashes = {}
       end
 
-      def register(schema)
+      def register(schema, name:)
         return nil if schema.blank?
 
-        schema_hash = compute_hash(schema)
-
-        if @schema_hashes.key?(schema_hash)
-          existing_name = @schema_hashes[schema_hash]
-          return { '$ref' => "#{SCHEMA_PATH_PREFIX}#{existing_name}" }
+        if @schemas.key?(name) && @schemas[name] != schema
+          raise ArgumentError, "Request body schema name '#{name}' is already registered"
         end
 
-        name = "RequestBody_#{short_hash(schema_hash)}"
         @schemas[name] = schema
-        @schema_hashes[schema_hash] = name
 
         { '$ref' => "#{SCHEMA_PATH_PREFIX}#{name}" }
       end
-
-      private
-
-      def compute_hash(schema)
-        normalized = normalize_for_hash(schema)
-        OpenSSL::Digest::SHA256.hexdigest(normalized.to_s)
-      end
-
-      def short_hash(full_hash)
-        full_hash[0, 12]
-      end
-
-      def normalize_for_hash(obj)
-        case obj
-        when Hash
-          obj.sort.map { |k, v| [k.to_s, normalize_for_hash(v)] }
-        when Array
-          obj.map { |v| normalize_for_hash(v) }
-        else
-          obj
-        end
-      end
     end
   end
 end

data/lib/gitlab/grape_openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Gitlab
   module GrapeOpenapi
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/gitlab-grape-openapi.rb

@@ -6,6 +6,7 @@ require_relative "gitlab/grape_openapi/configuration"
 require_relative "gitlab/grape_openapi/generator"
 require_relative "gitlab/grape_openapi/schema_registry"
 require_relative "gitlab/grape_openapi/request_body_registry"
+require_relative "gitlab/grape_openapi/operation_id_registry"
 require_relative "gitlab/grape_openapi/tag_registry"
 require_relative "gitlab/grape_openapi/normalized_path"
 
@@ -51,6 +52,9 @@ module Gitlab
   module GrapeOpenapi
     GenerationError = Class.new(StandardError)
 
+    # Raised when `config.info` is missing a title or version.
+    ConfigurationError = Class.new(GenerationError)
+
     # Raised when a route declares more than one optional path segment
     # containing a named parameter (e.g. `/foo(/:a)/bar(/:b)`).
     MultipleOptionalSegmentsError = Class.new(GenerationError)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -172,6 +172,7 @@ files:
 - lib/gitlab/grape_openapi/models/server_variable.rb
 - lib/gitlab/grape_openapi/models/tag.rb
 - lib/gitlab/grape_openapi/normalized_path.rb
+- lib/gitlab/grape_openapi/operation_id_registry.rb
 - lib/gitlab/grape_openapi/request_body_registry.rb
 - lib/gitlab/grape_openapi/schema_registry.rb
 - lib/gitlab/grape_openapi/serializers/time.rb