How to split openAPI/Swagger file into multiple valid sub-files?

Question

Our service implements different levels of access and we are using one openAPI YAML file internally.

For external documentation purposes, we would like to create multiple openAPI files, that are valid in themselves (self-sustained), but only have a partial set of the global file, e.g. based on the path or on tags.

(The same path may be used in different split-Files but I don't think that is a problem then.)

Any idea on how to achieve that? Is there some tooling around for it?

Answer 1

You can use a valid URI in a JSON Pointer which points to another resource. The URI can be a path to a local file, a web resource, etc.:

paths:
  /user/{id}:
    summary: Get a user
    parameters:
      - $ref: "./path/to/file#/user_id"

# And so on...

Reserved keys in the OpenAPI spec must be unique so I don't think you'd be able to create standalone OpenAPI specs without some third-party utility that could overcome that limitation.

However, you would be able to create valid standalone JSON objects defined across many files and reference them in the index document. There are many articles online providing examples:

• https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/
• https://blog.pchudzik.com/202004/open-api-and-external-ref/