gitlab-grape-openapi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5548e70ecc3368b56d965a6bbbc6ae8d448a8a230f0ff453c05d91fc3dfc4714
-  data.tar.gz: f535c2530fa0eed45b85b92805973d62dc294b3c7475fd6464229dea5113f1b2
+  metadata.gz: afbabc9163e59aafb950577da68e96bd817c5c4357e2eae88aabe4b75baaaf1f
+  data.tar.gz: 74a9b9a8abb13c4a122bf59169dd7aaa147162f68b781b47d729c52bd8440f50
 SHA512:
-  metadata.gz: 8410aab600a941dca435dd2da070dc1c68141cc5fea001452081216fd3b8f0714a1a87d39811ae9b482c55fc2350953c5bbe6979189631ad96a9d8641b7f42e8
-  data.tar.gz: d1ed6e54fc2819e34b8b2acfdd2ef9077647f5c11b4b3bf7de59dad8466a480f4240edb8e30b22fb1a6e8c747e088ed8d2632f3e92e92aa75555f69f7760895a
+  metadata.gz: c9af1518142acff74821ed05d46605c9f6e33b8f08ccc33d438324196467dc573d6661b48d5b9b247d362b8b864ce0909755d8952d3e1b302b077bfa03aa6b7f
+  data.tar.gz: 03161ba25486070010a7ec67f2955a42f5d82e46c0eb78dbb4065f5df49870b69d9927a78afa40b513c04e9075806005eb558354cf59f4db10946928001a6cb1

data/README.md

@@ -103,6 +103,7 @@ end
 | `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
 
@@ -212,6 +213,111 @@ bundle exec rspec
 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`.
+
+#### Verifying changes against `gitlab-org/gitlab`
+
+Because the monorepo consumes this gem from RubyGems, a change can pass
+this gem's own specs locally yet still break `gitlab-org/gitlab` CI once
+the published gem is pulled in. Verify both locally and in CI before
+releasing.
+
+**Locally**, point the monorepo's `Gemfile` at your working copy of this
+gem with a `path:` override:
+
+```ruby
+gem 'gitlab-grape-openapi', path: '<absolute path to this repo>', feature_category: :api
+```
+
+Run `bundle install` in the monorepo, then exercise the affected paths
+(for example regenerate the spec with `bin/rake gitlab:openapi:v3:generate`
+and run the relevant specs). When finished, revert with
+`git restore Gemfile Gemfile.lock` so the override does not leak into a
+commit.
+
+**In CI**, a `path:` override only sees your local checkout, so open a
+throwaway merge request in `gitlab-org/gitlab` that pins the `Gemfile` to
+the exact commit you want to test and let its pipeline run. Replace the
+dependency line:
+
+```ruby
+gem 'gitlab-grape-openapi', '~> <CURRENT_VERSION>', feature_category: :api
+```
+
+with a Git source:
+
+```ruby
+gem 'gitlab-grape-openapi',
+  git: 'https://gitlab.com/gitlab-org/ruby/gems/gitlab-grape-openapi.git',
+  ref: '<commit SHA>',
+  feature_category: :api
+```
+
+Pinning with `ref:` (rather than `branch:`) freezes the exact commit so
+CI does not drift if the branch moves. `Gemfile.next` is a symlink to
+`Gemfile`, so this single edit covers both. Run `bundle install` to
+regenerate `Gemfile.lock` with a GIT source block, commit it (do not
+hand-edit it), and push. To faithfully reproduce the real migration's CI
+conditions, also remove the in-tree gem under `gems/gitlab-grape-openapi/`
+and its `.gitlab/ci/gitlab-gems.gitlab-ci.yml` and `.gitlab/CODEOWNERS`
+entries, so Bundler cannot fall back to the vendored copy.
+
+This throwaway branch is verification-only — do not merge it. Once the
+gem is published, the real version bump uses a `'~> <NEW_VERSION>'`
+constraint instead of the Git source (see the post-release steps in
+`CLAUDE.md`).
+
 ## Contributing
 
 This gem is maintained by GitLab's API Platform team for internal use.

data/lib/gitlab/grape_openapi/configuration.rb

@@ -4,7 +4,7 @@ module Gitlab
   module GrapeOpenapi
     class Configuration
       attr_accessor :api_version, :api_prefix, :excluded_api_classes, :servers, :security_schemes, :info,
-        :tag_overrides, :annotations, :coercer_mappings
+        :tag_overrides, :annotations, :coercer_mappings, :warnings
 
       def initialize
         @api_prefix = "api"
@@ -18,6 +18,7 @@ module Gitlab
         @tag_overrides = {}
         @annotations = {}
         @coercer_mappings = {}
+        @warnings = false
       end
     end
   end

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

@@ -116,14 +116,19 @@ module Gitlab
           params
         end
 
-        # Emit a one-line stderr diagnostic identifying the route and API
+        # 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} " \

data/lib/gitlab/grape_openapi/version.rb

@@ -2,7 +2,6 @@
 
 module Gitlab
   module GrapeOpenapi
-    # Version of the gem
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-grape-openapi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - group::api
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: grape-entity
   requirement: !ruby/object:Gem::Requirement