OpenAPI v3: Improve path parameter (project) id

• Please check this box if this contribution uses AI-generated content (including content generated by GitLab Duo features) as outlined in the GitLab DCO & CLA. As a benefit of being a GitLab Community Contributor, you receive complimentary access to GitLab Duo.

What does this MR do and why?

OpenAPI v3: Improve path parameter (project) id

Summary

The purpose of this commit is to simplify the OpenAPI document by following the DRY pattern and using a single component ProjectIdOrPath for every path parameter "id".

Current Issues

Description Inconsistencies

• The ID or URL-encoded path of the project
• The ID or URL-encoded path of the project owned by the authenticated user
• The ID of the project (where type is integer)

Type Inconsistencies

• Some parameters are described with type 'string'
• Some parameters are described with type 'integer'

Proposed Changes

To address these inconsistencies, I propose using the anyOf structure to allow for both string and integer types. This approach aligns with the markdown documentation (cf example below) and provides clarity on the acceptable parameter types:

schema:
  anyOf:
    - type: string
      example: gitlab-org/gitlab
    - type: integer
      example: 278964

Examples

For example, for the endpoint GET /projects/{id}/badges/{badge_id}, the related markdown documentation clearly states the possibilities:

Get a badge of a project

Attribute: ID Type: integer or string

Additional Information

• I have also introduced a link to the namespaced-paths section in the parameter description to provide further clarity.

References

Screenshots or screen recordings

Before	After

How to set up and validate locally

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.