# Bundle

> Join a spec split over several files into one, for tools that can't follow $refs to other files.

```bash
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 `$ref`s reach, and writes one document. The portal itself follows `$ref`s across files, so it doesn't need this; code generators, gateways and review tools often do.

## 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. `$ref`s within the main file stay as they are.

```yaml title="specs/orders.yaml (before)"
schema:
  $ref: "./schemas/Order.yaml"
```

```yaml title="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`](/docs/tools/validate/) does. If it fails, nothing is written and the errors are listed (run `validate` on the source for file, line and column).

## 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 `$ref`s. 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.