Improve missing path-parameter handling

What does this MR do and why?

Two related changes to OperationConverter#inject_missing_path_parameters, both addressing the case where the source Grape route lacks a path-parameter declaration and the generator falls back to emitting schema: {} (valid OpenAPI 3.0 but missing type information).

1. Inherit declarations from mount parents

When a Grape API class is mounted under a parent that declares a path placeholder, Grape drops the parent's requires :id (etc.) from the child route's options[:params]. Previously the generator synthesized a schema: {} parameter for every such placeholder.

PathConverter now pre-passes the full route set and indexes every declared path placeholder by (path-prefix-up-to-placeholder, placeholder-name). OperationConverter looks each missing placeholder up in that index before falling back to an empty schema, so mounted child routes inherit the parent's declaration verbatim.

2. Diagnostic output for remaining synthesized parameters

Each placeholder that does fall through to the empty-schema fallback now emits a grep-friendly line to stderr identifying the route and the API class responsible:

[gitlab-grape-openapi] synthesized path param: POST /api/v4/foo placeholder=:bar class=API::Foo

From the class name, the source file follows GitLab's autoload conventions (API::Foo::Barlib/api/foo/bar.rb). This makes it straightforward for downstream consumers (e.g. CI checks, burn-down MRs) to pinpoint which routes still need a requires declaration.

The diagnostic only fires when a parameter is actually synthesized. Routes whose path placeholders are all declared (locally or via mount inheritance) produce no stderr output.

Real-world impact

Validated against the GitLab monorepo's doc/api/openapi/openapi_v3.yaml:

master (no changes):                                    474 entries with `schema: {}`
master + this MR (mount inheritance only):              57 entries (-88%)
master + this MR + monorepo MRs !238289 and !238294:    18 entries (-96%)

The remaining 18 are three separate residual defects (uneven placeholder names across mount chains, parens-optional segment classification, and one file-scope miss) that warrant their own follow-ups.

How to set up and validate locally

bundle install
bundle exec rspec
bundle exec rubocop lib/ spec/

The new fixture (spec/fixtures/apis/mounted_child_api.rb) demonstrates the mount pattern (mount ChildApi under params do; requires :id; end; resource :projects do; namespace ':id/...' do; ... end; end). The new specs in path_converter_spec.rb and operation_converter_spec.rb cover both the inheritance and the diagnostic — including the negative cases that the diagnostic emits no output when the placeholder is declared locally or inherited.

References

Related to: gitlab-org/gitlab#593537 (closed)

Edited by Alberto Bignotti

Merge request reports

Loading
Loading