Allow users to change the default OAPI 3.0 server for their self-managed GitLab instances

Summary

Currently, the OpenAPI v3 specification hardcodes the server URL as https://gitlab.com/api. While this ensures consistency across development environments and CI, it makes the spec incorrect for self-managed GitLab instances.

Proposal

Use OpenAPI 3.0 Server Variable Objects to make the server URL configurable:

servers:
  - url: https://{hostname}/api
    description: GitLab REST API
    variables:
      hostname:
        default: gitlab.com
        description: Your GitLab instance hostname

This approach would:

• Default to gitlab.com for GitLab.com users
• Allow self-managed users to substitute their own hostname
• Maintain consistency in the committed spec (no environment-specific URLs)
• Generate identical specs across all development environments and CI

Implementation considerations

1. Update config/initializers/gitlab_grape_openapi.rb to generate the server URL with a variable placeholder instead of a hardcoded URL
2. Verify that Scalar (our chosen documentation renderer) supports server variable overrides and provides a user-friendly way to change the hostname
3. Update documentation to explain how self-managed users can configure their instance hostname

How would users update the default server value

AI claims that need to be verified:

1. Scalar supports overriding servers via its configuration (servers property)
2. Scalar has onServerChange callback for detecting when server changes
3. Scalar has a baseServerURL option to prefix relative servers

They can be verified by testing directly in Scalar (to confirm the UI behavior), or by checking Scalar's docs/GitHub issues.

Related

• !218458 (merged) (comment thread starting at !218458 (comment 3010314174))
• !218276 (merged) (where the server URL was initially hardcoded to https://gitlab.com/api)