gitlab-grape-openapi 0.0.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1f4ea6abfdf3c4f4df8d30e3c25801d2e52b6f750ee1e8663b7e6ba84fed19d
-  data.tar.gz: 484cd5bb383b8936c966bb720dfc6c0be2febb0dd839f9ab2535124050d72b79
+  metadata.gz: 8f0408d05e90c29d726e2992e29455b1244d6dc028a28c9e63be8c1d4cfc1a23
+  data.tar.gz: 10157f62f24d46cb7e768fb141fdf391db6015d342f72f766b4225faa53919df
 SHA512:
-  metadata.gz: f20d63c31feaa71202b4dd517b5000097475102343ff4ab6b808958f795a42f9a73ad068c3b83f65ee3bf2bb658941f17e2a1b16c9a5eb9a61a55eb7ed5e3b23
-  data.tar.gz: 0c306ec014c6f0646ae25156107c5cbdf74033385cf5084313ee4285eb601b1eae1a3d679c7179b5af2bd5f0e36ac366f789424f930c7f24e8569ad0c0fdac57
+  metadata.gz: feb73a721b4d65eb5078105c4c21d360a86aeb93538164d115bf358fc38dadea00b5e2c177b23d2e5adc5cbae5c6172306c0ca4bb78a78a5a0a27f7154ef9f80
+  data.tar.gz: d61316ee6a5e1c20ae95e9f35430cff097d3b484301d2622ac426ee4355382b992dac5ae71db0dd492acf1f41eaa50b421b6d2bc86b52a99fd3af04f68cbc0b5

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 GitLab, Inc.
+Copyright (c) 2026 GitLab, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,278 @@
-# Gitlab::Grape::Openapi
+# GitLab Grape OpenAPI
 
-> [!warning] Reserved gem name
-> This gem is a placeholder to [reserve a gem name](https://docs.gitlab.com/development/gems/#reserve-a-gem-name)
+> [!IMPORTANT]
+> **Internal use only.** This gem exists to generate the OpenAPI 3.0 spec for
+> the [GitLab Rails monorepo](https://gitlab.com/gitlab-org/gitlab) and is not
+> intended for use outside of GitLab.
+>
+> - It is published to rubygems.org only so the monorepo's `Gemfile` can
+>   depend on it — not as a general-purpose Grape → OpenAPI tool.
+> - The public API, configuration DSL, and generated output may change in
+>   **any** release, including patch releases. There is no semantic-versioning
+>   contract.
+> - No external support is provided. Issues and merge requests from outside
+>   GitLab may be closed without review.
+> - Feature work is driven by the needs of `gitlab-org/gitlab`; capabilities
+>   that aren't needed there will not be added.
 
-Refer to [`gems/`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/gems?ref_type=heads) directory for actual implementation.
+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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'gitlab-grape-openapi'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Configure the gem using the `Gitlab::GrapeOpenapi.configure` block, typically in an initializer:
+
+```ruby
+Gitlab::GrapeOpenapi.configure do |config|
+  # Required: API metadata
+  config.info = Gitlab::GrapeOpenapi::Models::Info.new(
+    title: 'My API',
+    description: 'API description',
+    version: 'v1',
+    terms_of_service: 'https://example.com/terms'
+  )
+
+  # API path configuration
+  config.api_prefix = "api"    # Default: "api"
+  config.api_version = "v1"    # Default: "v1"
+
+  # Server definitions
+  config.servers = [
+    Gitlab::GrapeOpenapi::Models::Server.new(
+      url: 'https://{hostname}',
+      description: "Production API",
+      variables: {
+        hostname: Gitlab::GrapeOpenapi::Models::ServerVariable.new(
+          default: 'api.example.com',
+          description: 'API hostname'
+        )
+      }
+    )
+  ]
+
+  # Security schemes
+  config.security_schemes = [
+    Gitlab::GrapeOpenapi::Models::SecurityScheme.new(
+      name: "bearerAuth",
+      type: "http",
+      scheme: "bearer"
+    )
+  ]
+
+  # Exclude specific API classes from generation
+  config.excluded_api_classes = [
+    'API::Internal::Base',
+    'API::Internal::Admin'
+  ]
+
+  # Override tag names for better display
+  config.tag_overrides = {
+    'Ci' => 'CI',
+    'Oauth' => 'OAuth'
+  }
+
+  # Map Grape route settings to OpenAPI extensions
+  config.annotations = {
+    lifecycle: 'x-gitlab-lifecycle'
+  }
+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 |
+
+### Annotations
+
+The `annotations` configuration maps Grape route settings to OpenAPI vendor extensions. For example:
+
+```ruby
+config.annotations = {
+  lifecycle: 'x-gitlab-lifecycle'
+}
+
+When a Grape endpoint has:
+
+```ruby
+route_setting :lifecycle, 'mature'
+```
+
+The generated OpenAPI spec will include:
+
+```yaml
+x-gitlab-lifecycle: mature
+```
+
+## Usage
+
+### Generating an OpenAPI Specification
+
+```ruby
+# Load all API and entity classes
+Rails.application.eager_load!
+
+api_classes = API::Base.descendants
+entity_classes = Grape::Entity.descendants
+
+# Generate the specification
+spec = Gitlab::GrapeOpenapi.generate(
+  api_classes: api_classes,
+  entity_classes: entity_classes
+)
+
+# Output as JSON
+File.write('openapi.json', JSON.pretty_generate(spec))
+
+# Or as YAML
+require 'yaml'
+File.write('openapi.yaml', spec.to_yaml)
+```
+
+### Usage with `gitlab-org/gitlab`
+
+1. Start a Rails console in your GDK:
+
+   ```bash
+   cd ~/gdk/gitlab
+   rails console
+   ```
+
+2. Generate the OpenAPI specification:
+
+   ```ruby
+   Rails.application.eager_load!
+   api_classes = API::Base.descendants
+   entity_classes = Grape::Entity.descendants
+   spec = Gitlab::GrapeOpenapi.generate(api_classes: api_classes, entity_classes: entity_classes)
+   File.write(Rails.root.join('tmp', 'openapi.json'), JSON.pretty_generate(spec))
+   ```
+
+3. The spec will be saved to `tmp/openapi.json` in your GitLab directory.
+
+## Architecture
+
+The gem follows a converter-based architecture:
+
+```
+Generator
+├── TagConverter        - Extracts tags from API classes
+├── EntityConverter     - Converts Grape::Entity to OpenAPI schemas
+├── PathConverter       - Converts routes to OpenAPI paths
+│   ├── OperationConverter  - Converts individual endpoints
+│   ├── ParameterConverter  - Converts endpoint parameters
+│   ├── ResponseConverter   - Converts endpoint responses
+│   └── RequestBodyConverter - Converts request bodies
+└── TypeResolver        - Maps Ruby/Grape types to OpenAPI types
+```
+
+### Registries
+
+- **SchemaRegistry** - Tracks converted entity schemas
+- **RequestBodyRegistry** - Tracks request body schemas
+- **TagRegistry** - Tracks API tags
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Linting
+
+```bash
+bundle exec rubocop
+```
+
+### Releasing
+
+Releases are driven by the
+[gem-release CI component](https://gitlab.com/gitlab-org/components/gem-release)
+and a merge request whose title contains `RELEASE`.
+
+1. Open a merge request from the
+   [Release template](.gitlab/merge_request_templates/Release.md). The
+   `/title RELEASE: v<NEW_VERSION>` quick action ensures the title
+   contains `RELEASE`, which is what exposes the release-creation and
+   `gem-publication` jobs.
+2. Bump the `VERSION` constant in
+   `lib/gitlab/grape_openapi/version.rb` and fill in the changelog per
+   the template.
+3. Get the MR reviewed and merged. **Do not run the `gem-publication`
+   job from the MR pipeline** — it is meant to stay un-run during
+   review (see below).
+4. After merge, follow the post-release steps in `CLAUDE.md` to bump
+   the `gitlab-grape-openapi` version in `gitlab-org/gitlab` and
+   regenerate the committed `openapi_v3.yaml`.
+
+#### How publishing works
+
+`GEM_HOST_API_KEY` is configured as an **inherited, protected**
+variable on a parent group, so it is only exposed to pipelines running
+on protected branches or protected tags. This is why running the
+`gem-publication` job manually from the MR pipeline fails — the API key
+is not available there.
+
+The expected flow relies on the default branch being protected:
+
+- During review, the MR-pipeline `gem-publication` job stays un-run
+  (it is `manual`, and would fail anyway without the key).
+- When the version bump lands on the default branch (`main`), the
+  `gem-publication` job runs again — this time with the protected
+  `GEM_HOST_API_KEY` available — and publishes the gem to RubyGems.
+
+The gem-release component's rules that re-trigger publication after
+merge:
+
+```yaml
+.gem-release-default-rules:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+      changes: ["lib/**/version.rb"]
+    - if: '$CI_MERGE_REQUEST_TITLE =~ /RELEASE/ && "...dry_run..." == "true"'
+    - if: '$CI_MERGE_REQUEST_TITLE =~ /RELEASE/'
+      when: manual
+```
+
+The first rule is the one that publishes: a `push` to the default
+branch that changes `lib/**/version.rb`.
+
+## Contributing
+
+This gem is maintained by GitLab's API Platform team for internal use.
+External contributions are not actively solicited; issues and merge
+requests opened by non-GitLab contributors may be closed without review.
+GitLab team members should follow the [standard contribution guidelines](https://docs.gitlab.com/ee/development/contributing/) — see the [project page](https://gitlab.com/gitlab-org/ruby/gems/gitlab-grape-openapi).
+
+## License
+
+Released under the [MIT License](LICENSE).

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module FailFastAnnotatable
+        FAIL_FAST_ANNOTATION = '(validation stops on first error)'
+
+        private
+
+        def fail_fast_in_validations?(validations)
+          validations&.any? { |v| v.dig(:opts, :fail_fast) }
+        end
+
+        def annotate_fail_fast(desc)
+          return desc.to_s if desc.to_s.include?(FAIL_FAST_ANNOTATION)
+
+          "#{desc} #{FAIL_FAST_ANNOTATION}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# API::Validations::Validators::Limit is a custom validator unique to GitLab.
+# This resolver compares by class name string rather than constant reference so that this gem
+# does not blow up in environments where the validator is not defined.
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module LimitResolver
+        private
+
+        def limit_for(validations)
+          validation = validations&.find do |v|
+            v[:validator_class].name == 'API::Validations::Validators::Limit'
+          rescue NoMethodError
+            false
+          end
+          validation && validation[:options]
+        end
+
+        def apply_limit!(schema, validations)
+          return unless schema[:type] == 'string'
+
+          limit = limit_for(validations)
+          schema[:maxLength] = limit if limit.is_a?(Integer) && limit.positive?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "js_regex"
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      # Converts Ruby Regexp objects into ECMA-262 (JavaScript) compatible
+      # pattern strings for use in OpenAPI `pattern` schema fields.
+      #
+      # OpenAPI requires `pattern` values to be valid ECMA-262 regular
+      # expressions, but Ruby RegExes routinely contain constructs that ECMA-262
+      # cannot parse: \A / \z anchors, inline option groups like (?i-mx:...),
+      # POSIX classes, etc. js_regex translates these into JS-compatible equivalents.
+      #
+      # The Ruby /i flag is folded into the pattern itself (via character class
+      # expansion) so the resulting pattern carries no flags, which OpenAPI's
+      # flag-less `pattern` field requires
+      module RegexConverter
+        # js_regex's `target:` controls which ECMAScript version's regex
+        # features it will emit. ES2018 is the newest target the gem
+        # supports (as of 3.14.0); earlier targets like the default (ES5)
+        # silently drop lookbehinds, changing the semantics of any Ruby
+        # regex that relies on them
+        JS_REGEX_TARGET = 'ES2018'
+
+        def regexp_to_pattern(value)
+          regexp = extract_regexp(value)
+          return unless regexp
+
+          JsRegex.new(inline_case_insensitivity(regexp), target: JS_REGEX_TARGET).source
+        end
+
+        private
+
+        # Grape stores the validation's `:options` as the Regexp itself for
+        # `regexp: /.../`, or as a Hash `{ value: /.../, message: '...' }` for the
+        # long form. Pull the Regexp out of either shape
+        def extract_regexp(value)
+          return value if value.is_a?(Regexp)
+
+          value[:value] if value.is_a?(Hash) && value[:value].is_a?(Regexp)
+        end
+
+        # js_regex bakes case-insensitivity into character classes only when /i
+        # appears as an inline group; an outer /i flag survives as a JS-level
+        # option that we cannot represent in OpenAPI. Wrap the source in (?i:...)
+        # and drop the outer flag so js_regex expands the character classes
+        def inline_case_insensitivity(regexp)
+          return regexp if (regexp.options & Regexp::IGNORECASE).zero?
+
+          remaining_options = regexp.options & ~Regexp::IGNORECASE
+          Regexp.new("(?i:#{regexp.source})", remaining_options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Concerns
+      module Serializable
+        private
+
+        def serializable?(value)
+          return false if value.is_a?(Proc)
+          return false if defined?(ActiveSupport::TimeWithZone) && value.is_a?(ActiveSupport::TimeWithZone)
+          return false if value.is_a?(Time)
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/grape_openapi/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    class Configuration
+      attr_accessor :api_version, :api_prefix, :excluded_api_classes, :servers, :security_schemes, :info,
+        :tag_overrides, :annotations, :coercer_mappings, :warnings
+
+      def initialize
+        @api_prefix = "api"
+        @api_version = "v1"
+        @excluded_api_classes = []
+        @info = nil
+
+        @servers = []
+        @security_schemes = []
+
+        @tag_overrides = {}
+        @annotations = {}
+        @coercer_mappings = {}
+        @warnings = false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module GrapeOpenapi
+    module Converters
+      module CoercerResolver
+        def coercer_mapping_for(validations)
+          coercer_method = extract_coercer_method(validations)
+          return unless coercer_method # Validation doesn't use `coerce_with`
+          return if inline_proc?(coercer_method) # Inline Procs shouldn't need a coercer method
+
+          coercer_name = resolve_coercer_name(coercer_method)
+          config = Gitlab::GrapeOpenapi.configuration
+          mapping = config.coercer_mappings.find { |pattern, _mapping| coercer_name == pattern }&.last
+          return mapping if mapping
+
+          raise GenerationError,
+            "No OpenAPI schema mapping found for coercer '#{coercer_name}'. " \
+              "Add an entry for '#{coercer_name}' to coercer_mappings in " \
+              "config/initializers/gitlab_grape_openapi.rb, or use an inline lambda instead."
+        end
+
+        def build_coerced_schema(mapping)
+          schema = {}
+          schema[:type] = mapping[:type] if mapping[:type]
+          schema[:items] = { type: mapping[:items_type] } if mapping[:items_type]
+          schema[:format] = mapping[:format] if mapping[:format]
+          schema[:additionalProperties] = mapping[:additional_properties] if mapping[:additional_properties]
+
+          schema
+        end
+
+        private
+
+        def extract_coercer_method(validations)
+          return unless validations
+
+          coerce_validation = validations.find do |v|
+            v[:validator_class] == Grape::Validations::Validators::CoerceValidator
+          end
+          return unless coerce_validation
+
+          coerce_validation.dig(:options, :method)
+        end
+
+        def inline_proc?(coercer_method)
+          return false unless coercer_method.is_a?(Proc)
+
+          source_file, _line = coercer_method.source_location
+          return true unless source_file
+
+          source_file.exclude?('/validations/types/')
+        end
+
+        def resolve_coercer_name(coercer_method)
+          return coercer_name_from_source_location(coercer_method) if coercer_method.is_a?(Proc)
+
+          coercer_method.name.to_s
+        end
+
+        def coercer_name_from_source_location(coercer_method)
+          source_file, _line = coercer_method.source_location
+          return coercer_method.to_s unless source_file
+
+          camelize(File.basename(source_file, '.rb'))
+        end
+
+        def camelize(str)
+          str.split('_').map(&:capitalize).join
+        end
+      end
+    end
+  end
+end