How do you split a large OpenAPI specification across multiple files?

Large specs are commonly split into multiple files — often one file per resource or domain area — connected back together using $ref pointers that reference definitions in other files rather than requiring every schema and path to live in one enormous document.

# main openapi.yaml
paths:
  /users:
    $ref: './paths/users.yaml'
components:
  schemas:
    User:
      $ref: './schemas/user.yaml'

Each referenced file can itself be a complete, valid fragment describing just that one path or schema, and most tooling that consumes OpenAPI documents (Swagger UI, code generators, linters) resolves these cross-file $refs automatically, presenting the end result as if it were one unified document, without the consumer needing to know it was actually assembled from several files.

This pattern earns its complexity mainly once a spec grows large enough that one file becomes unwieldy to review in a pull request, or once multiple teams own different parts of the same API and want to make changes to their own resource files without merge conflicts in a single shared document; for smaller APIs, a single file is usually simpler to work with and not worth splitting prematurely.