Add support for custom OAPI annotations

Max Woolfrequested to merge
587171-grape-lifecycle-to-oapi-annotation into master

What does this MR do and why?

This merge request adds support for custom annotations in the GitLab Grape OpenAPI gem, which generates API documentation from code. The main change allows developers to add special metadata tags to their API endpoints that will appear in the generated documentation.

References

Issue: #587171 (closed)

How to set up and validate locally

  • Add a route_setting :lifecycle, 'some string' to any Grape file, for example: (This will cascade down to any nested routes automatically, which can be overriden)
    route_setting :lifecycle, :hello_world
    resources :audit_events do
      desc 'Get the list of audit events' do
        success ::API::Entities::AuditEvent
        is_array true
        tags %w[audit_events]
      end
  • Regenerate the V3 OpenAPI Spec bin/rake gitlab:openapi:v3:generate
  • Note the changes to the generated file which will include a x-gitlab-lifecycle annotation.

⚠️ MRs to constrain acceptable lifecycle values (beta, experiment, etc) is coming next.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #587171 (closed)

Merge request reports