Repository navigation
Support API mounting #2854
Description
This follows a comment on issue #647.
It would be great to be able to mount API specs onto another spec for service composition.
As an example, I have two independent services A and B, both having their own OAS files. I would like to 'merge' A and B together into a single, centralized spec.
If both services have, say, a /resource endpoint, I would like to discriminate them by prefixing their paths with the name of the services, /A and /B respectively (resulting in /A/resource and /B/resource).
One naive solution would be to list and redefine each path in the root OAS file and $ref the related A or B content, but changing the design of either A or B would require updating the root OAS file.
A possible alternative would be to support path nesting (discarded here):
paths:
'/A':
'/resource':
get:
# ....
'/B':
'/resource':
get:
# ....
I suggest considering introducing a mount field under Path Item Objects and taking a Paths Object:
paths:
'/A':
mount:
$ref: 'A.yaml#/paths'
'/B':
mount:
$ref: 'B.yaml#/paths'
Activity
SmallhillCZ commentedon Feb 15, 2022
I have the same use case, but I would rather show in some way, that under this path there is another API with its own spec and so I would rather reference not the paths included in its OAS, but the full OAS file. So more like a link to another API than a $ref.
nickshoe commentedon Feb 17, 2022
Another possibility could be to allow multiple
$refright underpaths:Assuming that the content of the referenced file is the following:
The root spec content would finally be rendered as:
Is this simplistic? I know that the current spec doesn't allow it, am I missing some hidden aspect about why it shouldn't be done this way in the first place?
MaxenceMaire commentedon Feb 28, 2022
@SmallhillCZ You make a good point. Especially since mounted APIs can live on different servers (or to specify useful metadata), I think it makes sense to include a complete OAS and not just the paths. A
$refcould still work though I guess? (e.g.$ref: 'A.yaml'instead of$ref: 'A.yaml#/paths').MaxenceMaire commentedon Feb 28, 2022
@nickshoe As you noted, the spec says the following about this:
Meaning only one
$refis evaluated (hence the idea of a new property). Replacingpathswith a list (instead of an object) would allow for multiple$ref, although it would also permit listing identical Path Item Objects multiple times (which I think is whypathsis an object in the first place).nickshoe commentedon Mar 2, 2022
@MaxenceMaire thanks for clarifying the use of
$ref.My example was an alternative proposal. Anyways, I like your proposal too (I've put a thumbs up).
We ended up defining separate OpenAPI documents for each microservice and using them independently. It would be nice to be able to squash together separate specs, without having to break them down according to the root keys of the spec. If conflicts arise, then one should handle them by changing one of the sub-specs.
gimbimloki commentedon Mar 7, 2023
@nickshoe @MaxenceMaire
I asked "Reference Objects in Paths Object".
As a rsult, it is duplicated keys and it is not allowed in YAML/JSON.
I think we should find another? altinative? way(add new field, list and something... ).
handrews commentedon Jan 27, 2024
I believe this is addressed by OAS 4 Moonwalk's separation of concerns principle. Specifically:
I'm going to close this as "moved to moonwalk", but please join the linked discussion if you are still interested!