How to bundle paths?

[rethab]

Hi, we have several api specs that we would like to bundle into one spec. We're trying to follow the example from the spec. In a file all.yaml:

paths:
  /users:
    $ref: '../resources/users.yaml'
  /users/{userId}:
    $ref: '../resources/users-by-id.yaml'

When I then run swagger-cli bundle all.yaml, it inlines the other yaml files 1:1 (starting with the line openapi: 3.0.0). Other things we tried:

• use $ref: '../resources/users.yaml#/paths --> inlines paths, but nested under /users
• modify the users.yaml to only contain a list of paths --> similar output as previous

How can we correctly bundle all paths? Note that bundling schemas/models works though. It's just paths that don't work

[JamesMessinger]

There's a subtle difference between bundling and stitching. This CLI currently only provides the former, not the latter.

Bundling is simply a matter of resolve $ref pointers and inlining whatever they point to. So in your example above, you could use $ref: ../resources/users.yaml#/paths/~1users to copy the /users path from users.yaml into all.yaml.

Stitching is a "smarter" version of bundling that is specifically aware of the structure of Swagger/OpenAPI files and understands the semantics of the files well enough to merge them together correctly. This is not currently supported by swagger-cli, but you can accomplish the same goal using bundling as described above.

[rethab]

Hi @JamesMessinger thanks for the response. Is there any doc on how things like ~1 behave? I only found this doc from openapi, but can't find anything about that there: https://swagger.io/docs/specification/using-ref/

[JamesMessinger]

The OpenAPI spec builds off a few other specs, namely JSON Schema, JSON Reference, and JSON Pointer. The $ref properties in an OpenAPI document are JSON References, and the values of those references are JSON Pointers.

The ~1 escape sequence is defined in Section 4 of the JSON Pointer Spec

[rethab]

Thanks @JamesMessinger I didn't know that :+1: