[go: up one dir, main page]

Investigate feasibility of Grape -> rswag request spec converter

Based on discussions in #563371 (closed), this issue tracks a feasibility study to determine whether we should create a Grape -> rswag request spec converter as an alternative approach to generating OpenAPI 3.0 specifications.

Background

From Vlad's proposal in #563371 (closed), this would be a "combo solution" that:

  • Builds a custom grape -> rswag converter (external gem or internal class)
  • Uses the rswag gem (which is up to date and well maintained) to generate OpenAPI 3.0 specs
  • Would allow for bi-directional development in the future (API design first workflow)

Feasibility Study Tasks

1. Audit Existing Request Specs Landscape

  • Inventory current request specs in the GitLab codebase
  • Identify patterns and structures used in existing request specs
  • Document gaps where request specs don't exist for API endpoints
  • Assess the volume of work required to achieve comprehensive coverage

Summary

  • There seems to be comprehensive coverage of all the REST API endpoints (in terms of files that cover all the API classes)
  • There are 300 API classes (Classes that define endpoints/routing + base classes and helpers)
  • There are 293 actual endpoints API::API.enpoints.count
  • There are 1108 routes total (including internal, CE, EE, http methods + named paths ie. projects/:id/issues/:subscribable_id/subscribe) API::API.routes.count

Patterns/Gaps

  • there are a few api classes that generate routes for other endpoints example - API::Subscriptions
  • API::Subscriptions generates subscription routes for merge_requests, issues, project_labels and group_labels)
  • the tests for these routes are included in the specs for the "subscribable" api class (ie the merge_requests_spec includes a test for POST :id/merge_requests/:merge_request_iid/subscribe
  • the spec folder lib/api/requests includes a request spec folder for the grapql api (so they are mixed in together?) /api/:version/projects/:id/merge_requests/:subscribable_id/subscribe with :version as a variable
  • some specs explicitly use "v4" in the request path being tested and some rely on the api spec helper which uses a default version generated by API::API.version which is v4
  • there are some inconsistent naming patterns /api/:version/internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription spec => ee/spec/requests/api/gitlab_subscriptions/subscriptions_spec.rb
  • Most of the inconsistencies seem to relate to internal api endpoints
  • when generating our openapi2 specs or in any of the grape definitions we do not distinguish between ee and ce api routes/endpoints
  • we do not currently mount any EE api endpoints in our openapi2 specs
  • we do not currently distinguish in our entity or grape api definitions between ee and ce routes, schema structure, params etc

Coverage

  • coverage does not seem to be the issue

Intitial observations/concerns

  • there is a fair amount of metaprogramming that adds extra routes to namespaced endpoints, for example subscribable or awardable routes are added to issues, merge_requests, group/epics
  • with a rswag converter, it would be difficult to automate adding subscribable routes to each of the intended endpoint rswag specs
  • there is no way to distinguish between ee and ce endpoints for openapi spec generation
  • Maybe exclude internal api in first iteration?? This is where the majority of naming inconsistencies occur and more manual verification would need to happen for any conversion method we choose

2. Analyze rswag DSL Requirements

  • Study the rswag DSL structure and requirements for generating OpenAPI 3.0 specs
  • Map Grape route definitions to rswag spec format
  • Identify transformation logic needed for common patterns (parameters, responses, authentication, etc.)
  • Document any rswag limitations that might affect our use case

First draft !204430 (closed) of POC converter

3. Compare with Alternative Approaches

  • Evaluate effort required vs. building a direct Grape -> OpenAPI 3.0 converter
  • Assess maintenance overhead and long-term sustainability
  • Document pros/cons of each approach

Success Criteria

This feasibility study should provide clear answers to:

  1. Is a Grape -> rswag converter technically viable?
  2. What would be the approximate development effort required?
  3. How does this approach compare to alternatives in terms of effort and maintainability?
  4. Are there any show-stopping technical limitations?
Edited by Vlad Wolanyk