search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.91k stars 9.07k forks source link

change specification to permit $ref of server objects #2338

Closed nlundquist closed 4 months ago

nlundquist commented 4 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 1 year ago

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

0xtuytuy commented 1 year ago

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

bambamboole commented 6 months ago

Any news here ? I just ran into this issue 🙈

handrews commented 6 months ago

@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.

handrews commented 4 months ago

Consolidating under #3853 and closing