mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-09 20:57:44 +00:00
daf030b7a8
* Remove extra 'resources' landing page, redirect from main one * Move custom plugins file to its own directory, add redirect to handle * docs: split the custom plugins page into one page per feature * docs: extend decorators explanation and link to it from the custom plugins section * docs: Fix all the links that were broken when I moved things * Apply excellent suggestions from code review Co-authored-by: Heather Cloward <heathercloward@gmail.com> * docs: Add examples of how to use the custom rule * docs: Replace the nested visitor example with an object rather than a function * Update custom-rules.md minor consistency edits * Apply suggestions from code review Co-authored-by: Heather Cloward <heathercloward@gmail.com> * docs: clearer explanation of skip, and finish a broken sentence * Update docs/custom-plugins/index.md Co-authored-by: Heather Cloward <heathercloward@gmail.com> * Apply suggestions from code review Co-authored-by: Adam Altman <adam@redoc.ly> * docs: use object rather than function for visitor --------- Co-authored-by: Heather Cloward <heathercloward@gmail.com> Co-authored-by: Adam Altman <adam@redoc.ly>
185 lines
11 KiB
Markdown
185 lines
11 KiB
Markdown
# `bundle`
|
|
|
|
## Introduction
|
|
|
|
API definitions can grow and become difficult to manage, especially if several teams are collaborating on them. It's a good practice to maintain the reusable parts as separate files, and include them in the main (root) API definition by referencing them with `$ref`. However, most OpenAPI tools don't support that multi-file approach, and require a single-file API definition.
|
|
|
|
Redocly CLI can help you combine separate API definition files (such as if you used the `split` command) into one. The `bundle` command pulls the relevant parts of an API definition into a single file output in JSON or YAML format.
|
|
|
|
The `bundle` command first executes preprocessors, then rules, then decorators.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
redocly bundle <apis>...
|
|
redocly bundle <apis> [--max-problems=<n>]
|
|
redocly bundle <apis> [--lint] [--config=<path>]
|
|
redocly bundle <apis>... -o <outputName> --ext <ext>
|
|
redocly bundle --version
|
|
```
|
|
|
|
## Options
|
|
|
|
| Option | Type | Description |
|
|
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| apis | [string] | List of API root definition filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file. |
|
|
| --config | string | Specify path to the [config file](#custom-configuration-file). |
|
|
| --dereferenced, -d | boolean | Generate fully dereferenced bundle. |
|
|
| --ext | string | Specify bundled file extension. Possible values are `json`, `yaml`, or `yml`. Default value is `yaml`. |
|
|
| --extends | [string] | Can be used in combination with `--lint` to [extend a specific configuration](./lint.md#extend-configuration). Default values are taken from the Redocly configuration file. |
|
|
| --force, -f | boolean | Generate bundle output even when errors occur. |
|
|
| --format | string | Format for the output. Possible values are `codeframe`, `stylish`, `json`, or `checkstyle`. Default value is `codeframe`. |
|
|
| --help | boolean | Show help. |
|
|
| --keep-url-references, -k | boolean | Keep absolute url references. |
|
|
| --lint | boolean | Lint definition files. Default value is `false`. |
|
|
| --max-problems | integer | Truncate output to display the specified maximum number of problems. Default value is `100`. |
|
|
| --metafile | string | Path for the bundle metadata file. |
|
|
| --output, -o | string | Name or folder for the bundle file. If you don't specify the file extension, `.yaml` is used by default. If the specified folder doesn't exist, it's created automatically. **If the file specified as the bundler's output already exists, it's overwritten.** |
|
|
| --remove-unused-components | boolean | Remove unused components from the `bundle` output. |
|
|
| --skip-decorator | [string] | Ignore certain decorators. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). |
|
|
| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). |
|
|
| --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). |
|
|
| --version | boolean | Show version number. |
|
|
|
|
## Examples
|
|
|
|
### Bundle a single API definition
|
|
|
|
This command creates a bundled file at the path `dist/openapi.json` starting from the root API definition file `openapi/openapi.yaml` and following the `$ref` to other files if appropriate. The bundled file is in JSON format.
|
|
|
|
```bash
|
|
redocly bundle openapi/openapi.yaml --output dist/openapi.json
|
|
```
|
|
|
|
### Bundle multiple API definitions
|
|
|
|
This command creates one bundled file for each of the specified apis in the `dist/` folder. Bundled files are in JSON format.
|
|
|
|
```bash Command
|
|
redocly bundle --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml
|
|
```
|
|
|
|
```bash Output
|
|
dist/openapi.json
|
|
dist/petstore.json
|
|
```
|
|
|
|
### Create a fully dereferenced bundle
|
|
|
|
A fully dereferenced bundle does not use `$ref` at all, all the references are resolved and placed into the definition file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the `$ref` syntax.
|
|
|
|
```bash
|
|
redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml
|
|
```
|
|
|
|
:::warning Note
|
|
|
|
JSON output only works when there are no circular references.
|
|
|
|
:::
|
|
|
|
### Custom configuration file
|
|
|
|
By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
|
|
|
|
```bash
|
|
redocly bundle --config=./another/directory/config.yaml
|
|
```
|
|
|
|
### Format
|
|
|
|
#### Codeframe (default)
|
|
|
|
```bash
|
|
redocly bundle pet.yaml store.yaml -o ./bundled --format=codeframe
|
|
## equivalent to: redocly bundle pet.yaml store.yaml -o ./bundled
|
|
```
|
|
|
|
Note: Errors display in the following format: `file:line:column`. For example, `petstore-with-errors.yaml:16:3`.
|
|
|
|
Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.
|
|
|
|
#### Stylish
|
|
|
|
```bash
|
|
redocly bundle pet.yaml store.yaml -o ./bundled --format=stylish
|
|
```
|
|
|
|
In this format, `bundle` shows the filename, line number, and column where the problem occurred.
|
|
|
|
The compressed output omits other contexts and suggestions.
|
|
|
|
#### JSON
|
|
|
|
```bash Command
|
|
redocly bundle pet.yaml store.yaml -o ./bundled --format=json
|
|
```
|
|
|
|
```bash Output
|
|
bundling pet.yaml...
|
|
{
|
|
"totals": {
|
|
"errors": 0,
|
|
"warnings": 0,
|
|
"ignored": 0
|
|
},
|
|
"version": "1.0.0-beta.54",
|
|
"problems": []
|
|
}📦 Created a bundle for pet.yaml at bundled/pet.yaml 28ms.
|
|
bundling store.yaml...
|
|
{
|
|
"totals": {
|
|
"errors": 0,
|
|
"warnings": 0,
|
|
"ignored": 0
|
|
},
|
|
"version": "1.0.0-beta.54",
|
|
"problems": []
|
|
}📦 Created a bundle for store.yaml at bundled/store.yaml 15ms.
|
|
```
|
|
|
|
In this format, `bundle` shows the result of bundling (including the number of errors and warnings and their descriptions) in JSON-like output.
|
|
|
|
#### Checkstyle
|
|
|
|
```bash Command
|
|
redocly bundle pet.yaml -o ./bundled --lint --format=checkstyle
|
|
```
|
|
|
|
```bash Output
|
|
bundling pet.yaml...
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<checkstyle version="4.3">
|
|
<file name="pet.yaml">
|
|
</file>
|
|
</checkstyle>
|
|
📦 Created a bundle for pet.yaml at bundled/pet.yaml 35ms.
|
|
```
|
|
|
|
In this format, `bundle` uses the [Checkstyle](https://checkstyle.org/) XML report format.
|
|
Due to the limitations of this format, the output _only_ includes the filename, line, column, severity,
|
|
and rule ID (in the `source` attribute).
|
|
All other information is omitted.
|
|
|
|
### Skip preprocessor, rule, or decorator
|
|
|
|
You may want to skip specific preprocessors, rules, or decorators upon running the command.
|
|
|
|
```bash Skip preprocessors
|
|
redocly bundle --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
|
|
```
|
|
|
|
```bash Skip rules
|
|
redocly bundle --skip-rule=no-sibling-refs --skip-rule=no-parent-tags
|
|
```
|
|
|
|
```bash Skip decorators
|
|
redocly bundle --skip-decorator=generate-code-samples --skip-decorator=remove-internal-operations
|
|
```
|
|
|
|
:::success Tip
|
|
|
|
To learn more about preprocessors, rules, and decorators, refer to the [custom plugins](../custom-plugins/index.md) page.
|
|
|
|
:::
|