apigeniebundle

bundle

Bundles an OpenAPI, Swagger or AsyncAPI schema and the files it references, or a Protobuf (.proto) file and the files it imports, into a single file.

Usage

apigenie bundle [OPTIONS] --output OUTPUT INPUT

Description

The command recognizes Protobuf files by the .proto extension. Other files are read as JSON or YAML, and recognized as OpenAPI, Swagger or AsyncAPI schemas by the openapi, swagger or asyncapi property of the document root.

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. 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. 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. 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:

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

Option Description
-o, --output OUTPUT Path to the bundled file. Required.
-I, --proto-path DIR Directory in which Protobuf imports are searched.

–output OUTPUT

Path of the bundled file.

–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