Support API mounting

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'

[nickshoe]

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

[MaxenceMaire]

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.

@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 $ref could still work though I guess? (e.g. $ref: 'A.yaml' instead of $ref: 'A.yaml#/paths').