Documentation ¶
Overview ¶
genoapi generates OpenAPI files from .proto definitions and other sources of CUE constraints. It requires the definition of a configuration file that is specified at the Go or CUE module root for which one wishes to generate the OpenAPI files.
Generation adopts the Proto <-> JSON mappings conventions. Most notably, field names are converted to JSON names.
Generation involves the following steps:
- Convert .proto files to CUE files
- Validate the consistency of the CUE defintions
- Convert CUE files to self-contained OpenAPI files.
Each of which is documented in more detail below. 1. Converting Proto to CUE
genoapi generates all .proto files using a single builder. As the Istio OpenAPI files are self-contained, this is not strictly necessary, but it allows for better checking and works better if one wants to generate the intermediate CUE results for evaluation.
Field names are mapped using JSON naming.
Protobuf definitions may contain (cue.val) and (cue.opt) options to annotate fields with constraints.
Caveats:
- It is assumed that the input .proto files are valid and compile with protoc. The conversion may ignore errors if files are invalid.
- CUE package names share the same naming conventions as Go packages. CUE requires the go_package option to exist and be well-defined. Note that some of the gogoproto go_package definition are illformed. Be sure to use the original .proto files for the google protobuf types.
2. Combine and validate generated CUE
CUE files that reside in the same directory as a .proto file and that have the same package name as the corresponding Go package are automatically merged into the generated CUE definitions. Merging happens based on the generated CUE names.
The combines CUE definitions are validated for consistency before proceeding to the next step. 3. Converting CUE to OpenAPI
In this step a self-contained OpenAPI definition is generated for each directory containing proto definitions. Files are made self-contained by including a schema definition for each imported type within the OpenAPI spec itself. To avoid name collissions, types are, by convention, prefixed with their proto package name.
Possible extensions to the generation pipeline ¶
The generation pipeline can be augmented by injecting CUE from other sources before step 2. As combining CUE sources is a commutative operation, order of injection does not matter and there is no need for the user to be explicit about any order or injection points.
Examples of other possible CUE sources are: - constraints extracted from Go code