apigenie bundle
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 and i18n, which compare and extract one file at a time.
Usage
apigenie bundle [OPTIONS] --output OUTPUT INPUT
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
formatcommand. - 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_packageorjava_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:
syntax = "proto3";
package shop.v1;
import "common/money.proto";
message Order {
common.v1.Money total = 1;
}
and common/money.proto:
syntax = "proto3";
package common.v1;
message Money {
string currency = 1;
int64 units = 2;
}
apigenie bundle shop.proto --output bundle.proto writes:
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.
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 shared by the five binaries.