change specification to permit $ref of server objects

[nlundquist]

The spec forbids the use of $refs to define entries in the servers array. The unfortunate result of this is duplication of information in several specification files, even though the services defined in these specs are all hosted behind the same ingress host.

Aside from this issue confirming the problem: https://github.com/OAI/OpenAPI-Specification/issues/1527, I couldn't find any discussion around this.

I'm guessing that the design rationale was all the endpoints present on a host/ingress ought to be defined in the same file, so there's no need to share server definitions. However, considering that a very large number of services, each with their own versioning, built by differing teams, could all be hosted on a single ingress- it becomes attractive to allow each service to own their own OpenAPI spec.

However, with this duplicated sever information now in each service's spec files, potentially dozens of files will need to be updated when a server object change occurs.

Has this issue been discussed by the committee before? What downsides are there to allowing this that I'm failing to see?

Thanks for considering this request maintainers 🙏

[gskema]

Use case: we have over 600 endpoints and over 200 different servers, server/endpoint combination depend on multiple configuration factors. I wanted to generate a single file for documentation and be fully accurate what endpoint is available on which server. By inlining explicit server list for each operation the file is already over 100K lines. $ref would be really useful. For now I have to resort to x-server-lists component (10K lines).

[AMorgaut]

Use Case:

I have the same issue regarding a back-for-frontend which host many independant services, all with their own versionning and ownership, then defined in many separated Open API files with associated service test files.

Theses back-for-frontend components share several servers domains (with path level routing) due to the local, stagings (team integration, uat, ppd), and production environnements

We really don't want to copy-paste this server list in all the open api files with the need to update them all when a server configuration update occurs

[shreelakshmijoshi]

Hi, Is there any update on referencing the server using $ref?

[0xtuytuy]

Is there any update on this? This would be key for us!

[bambamboole]

Any news here ? I just ran into this issue 🙈

[handrews]

@bambamboole @0xtuytuy we plan to do a smallish 3.2 this year, and we'll audit everything tagged re-us: ref-everywhere then to see how much we want to open up referencing. (I'm personally in favor of allowing referencing for most if not all named Objects). We are also considering revamping servers / deployments entirely in OAS 4 "Moonwalk" (in the OAI/sig-moonwalk repository), and it might be possible to backport that to 3.x and solve the same problem in a different way.