Skip to content
Portal

Bundle

npx rapidoc bundle openapi.yaml -o dist/openapi.json
npx rapidoc bundle openapi.yaml > openapi.bundled.yaml
npx rapidoc bundle --api orders -o dist/orders.yaml   # an API of rapidoc.config.*

rapidoc bundle loads a spec and every file its $refs reach, and writes one document. The portal itself follows $refs across files, so it doesn’t need this; code generators, gateways and review tools often do.

What it writes

Section titled “What it writes”

Every $ref to another file becomes a component, holding a copy of what it pointed to, and the $ref is rewritten to point there. $refs within the main file stay as they are.

specs/orders.yaml (before)
schema:
  $ref: "./schemas/Order.yaml"
dist/orders.yaml (after)
schema:
  $ref: "#/components/schemas/Order"
# ...
components:
  schemas:
    Order:
      type: object
      # ... from schemas/Order.yaml, its own $refs rewritten the same way
  • The component goes where the $ref is written: a schema under components/schemas, a parameter under components/parameters, and so on for responses, request bodies, headers, examples, links, callbacks and (OpenAPI 3.1) path items. In Swagger 2.0 they go under definitions, parameters and responses.
  • The name is the file’s name (Order.yaml → Order) or, for file.yaml#/NotFound, the last part of the pointer. The same target referenced from several places is copied once. A name already taken by something else gets -2, -3.
  • A $ref where the kind can’t be told (under a vendor extension, say) is inlined.
  • Keys keep their order; comments are not kept (the output is data).

Before writing, the result is checked against the OpenAPI Specification, like rapidoc validate does. If it fails, nothing is written and the errors are listed (run validate on the source for file, line and column).

Options

Section titled “Options”
Option Meaning
-o, --output <file> Write here, as JSON or YAML by the extension; folders are created. Without it the document goes to stdout (YAML).
--format yaml | json The output format, when the extension shouldn’t decide (or for stdout).
--dereference Inline every $ref, in-file ones too, so the output has none. A recursive schema can’t be inlined: the command stops and names the cycle.
--no-validate Write the result without checking it against the specification.
--remote Also fetch remote $refs. Without it they are left as they are, with a warning.
--api <id> Bundle the spec of this API from rapidoc.config.* (its default version) instead of a file. Needs @rapidoc/portal.

Exit code 1 when a $ref points to nothing (reported with file, line and column), when the result isn’t valid OpenAPI, or when --dereference meets a cycle; nothing is written in those cases.