# apigenie bundle

Source: https://apigenie.pl/docs/reference/cli/bundle
Part of the reference of [apigenie](https://apigenie.pl/docs/reference/cli.md).
Its other pages: [changelog](https://apigenie.pl/docs/reference/cli/changelog.md), [config](https://apigenie.pl/docs/reference/cli/config.md), [convert](https://apigenie.pl/docs/reference/cli/convert.md), [credits](https://apigenie.pl/docs/reference/cli/credits.md), [diff](https://apigenie.pl/docs/reference/cli/diff.md), [evolve](https://apigenie.pl/docs/reference/cli/evolve.md), [format](https://apigenie.pl/docs/reference/cli/format.md), [i18n](https://apigenie.pl/docs/reference/cli/i18n.md), [init](https://apigenie.pl/docs/reference/cli/init.md), [license](https://apigenie.pl/docs/reference/cli/license.md), [lint](https://apigenie.pl/docs/reference/cli/lint.md), [overlay](https://apigenie.pl/docs/reference/cli/overlay.md), [test](https://apigenie.pl/docs/reference/cli/test.md).

Bundles an OpenAPI, Swagger 2.0 or AsyncAPI document and the local files it references, or a
Protobuf file and the files it imports, into one file that stands on its own: for tools that read
a single document, and before [diff](/docs/reference/cli/diff) and [i18n](/docs/reference/cli/i18n),
which compare and extract one file at a time.

## Usage

```sh
apigenie bundle [OPTIONS] --output OUTPUT INPUT
```

```sh
apigenie bundle api/openapi.yaml --output build/openapi.json
apigenie bundle api/orders.proto -I shared -I api --output build/orders.proto
```

## What the command does

A file with the `.proto` extension is a Protobuf file. Any other file is read as JSON or YAML and
recognized as an OpenAPI, Swagger or AsyncAPI document by the `openapi`, `swagger` or `asyncapi`
field of its root; a file with none of them is reported
(`'FILE' is not an OpenAPI, Swagger or AsyncAPI document.`) and nothing is written.

Unlike `format`, `overlay` and `lint --fix`, `bundle` does not keep the YAML
comments of OpenAPI, Swagger and AsyncAPI inputs: the output is a new document
built from several files. In YAML output, strings that YAML 1.1 parsers would
read as booleans or numbers, such as `yes`, `off`, `0755` or `1:30`, are written
in double quotes.

### OpenAPI

External references (`$ref` to other local files) are copied into the
`components` object of the output, and the references are rewritten to point
there. A copy is named after the last segment of the reference (`Address` for
`models.yaml#/$defs/Address`), and a copy of a whole file after the file (`pet`
for `pet.yaml`). When the name is taken, a numeric suffix is added (`_2`, `_3`,
and so on). Since 0.12.0, a component that is only a reference to the same name
in another file takes the referenced content instead. `PhoneNumber: {$ref:
common.yaml#/components/schemas/PhoneNumber}` becomes the `PhoneNumber` schema
of `common.yaml`, and no `PhoneNumber_2` is added. A reference to a whole file
is still copied (`pet: {$ref: pet.yaml}` gives `pet_2`). Remote references
(URLs) are not supported. The output format, JSON or YAML, follows the extension
of the output file.

### Swagger

Swagger 2.0 documents are bundled like OpenAPI ones. Schemas, parameters and
responses referenced in other local files are copied into the `definitions`,
`parameters` and `responses` objects of the output, and the references are
rewritten to point there. The copies are named as OpenAPI components are. A
definition, parameter or response that is only a reference to the same name in
another file takes the referenced content (since 0.12.0). A reference to a whole
file is still copied. A path item that is a reference to another file takes the
content of that file. Remote references (URLs) are not supported. The output
format, JSON or YAML, follows the extension of the output file.

### AsyncAPI

AsyncAPI 3.x documents are bundled with the local files they reference. Root
servers, channels and operations kept in other files take the content of those
files; other referenced objects become components. A component that is only a
reference to another local file takes the referenced content. Schemas in other
formats, such as Avro, are copied as they are, and references by URL are kept.
The output format, JSON or YAML, follows the extension of the output file.

### Protobuf

The input file and the files it imports, directly or indirectly, are combined
into one proto3 file, which can be compiled without the imported files:

- All declarations of the input file are kept, in their order, with their
  comments. The output is written in the layout of the `format` command.
- Of the imported files, only the messages, enums and extensions that the
  input file uses, directly or through other imported declarations, are
  copied. They follow the declarations of the input file. Imported services,
  unused declarations and the file options of imported files (such as
  `go_package` or `java_package`) are left out.
- The output has the package of the input file. Declarations from files with
  another package are renamed with a prefix made from their package: top-level
  messages and enums get the package in PascalCase, and top-level extensions
  get it in snake case. Declarations nested in them keep their names. When a
  name is already taken, a numeric suffix is added (`_2`, `_3`, and so on).
  Type names and option names that refer to renamed declarations are
  rewritten. Declarations from files with the same package keep their names.
- The well-known types (`google/protobuf/*.proto`) are not bundled: their
  imports are kept, and the imports needed by the copied declarations are
  added.

For example, with `shop.proto`:

```proto
syntax = "proto3";

package shop.v1;

import "common/money.proto";

message Order {
  common.v1.Money total = 1;
}
```

and `common/money.proto`:

```proto
syntax = "proto3";

package common.v1;

message Money {
  string currency = 1;
  int64 units = 2;
}
```

`apigenie bundle shop.proto --output bundle.proto` writes:

```proto
syntax = "proto3";

package shop.v1;

message Order {
  CommonV1Money total = 1;
}

message CommonV1Money {
  string currency = 1;
  int64 units = 2;
}
```

Renaming changes the full names of the moved declarations, e.g.
`common.v1.Money` becomes `shop.v1.CommonV1Money`, and an option such as
`(google.api.http)` becomes `(google_api_http)`. Field numbers and the wire
format do not change, but tools that depend on full names, such as JSON
encoding of `Any` values or code generators matching option names, see the new
names. Type names inside string option values are not rewritten.

Imports are searched in the proto paths given with `--proto-path`, like
`protoc` does, never relative to the importing file. Without `--proto-path`,
the directory of the input file is searched.

Nothing is written when there are errors. The command reports, with the file,
line and column:

- imports that are not found or cannot be read, including proto2 files and
  files with editions, which are not supported
- import cycles
- type names and option names that are not defined, or not visible from the
  file that uses them
- enum values that clash after the merge; enum values are in the scope of the
  package, so they cannot be renamed

## Options

### --output OUTPUT

The bundled file; `-o OUTPUT` for short. Required. For an OpenAPI, Swagger or AsyncAPI document
the extension, `.json` or `.yaml`, chooses the format.

### --proto-path DIR

Directory in which Protobuf imports are searched. The option can be repeated;
the directories are searched in the given order. Write it as `-I DIR` or
`--proto-path=DIR`. Defaults to the directory of the input file.

```sh
apigenie bundle api/orders.proto -I shared -I api --output bundle.proto
```

## Exit status

| Status | When                                                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 0      | The bundled file was written.                                                                                                                                                        |
| 2      | The input is not a supported document, cannot be read (`Errors reading OpenAPI file 'FILE':` and the positions), or, for a Protobuf file, has the errors listed above; nothing is written. |

See the [exit statuses](/docs/reference/cli#exit-status) shared by the five binaries.

## See also

- [diff](/docs/reference/cli/diff): Compares two bundled versions, imported declarations included.
- [i18n](/docs/reference/cli/i18n): Extracts the texts of a bundled document, referenced files included.
- [format](/docs/reference/cli/format): The layout a bundled Protobuf file is written in.
