Command line
The command line has six commands. cargo honig --help lists them:
cargo honig: OpenAPI 3.2 to a Rust client and server
Usage: cargo honig [OPTIONS] <COMMAND>
Commands:
init Add the module `api` to Cargo.toml and the `honig` dependency with your adapters
generate Generate the modules set in Cargo.toml files
check Fail if a module is stale
validate Validate under its own OpenAPI version and print diagnostics
upgrade Print the document upgraded to OpenAPI 3.2 JSON
bundle Print a description split over files as one document, in its own OpenAPI version
help Print this message or the help of the given subcommand(s)
Options:
--manifest-path <PATH> Cargo.toml to use [default: Cargo.toml]
-q, --quiet Only print errors
-h, --help Print help
-V, --version Print version
SETTINGS ([package.metadata.honig.<module>] in Cargo.toml): spec, output, client, server, tests, unknown_fields, overlays, formats, derives
The Settings page of the book explains each one: https://alphajack.github.io/honig/settings.html
Check a description
validate reads a description under its own version and prints what is wrong. It exits with 1 on an error.
$ cargo honig validate openapi.yaml
ok: openapi.yaml
$ cargo honig validate broken.yaml
error: /info: missing field `version`
Each diagnostic starts with a JSON pointer into the document.
See what honig reads
upgrade prints the document as honig generates from it: OpenAPI 3.2 JSON.
Run it to see what a Swagger 2.0 or 3.0 description becomes before you generate.
cargo honig upgrade swagger.yaml > openapi.json
Upgrading lists what changes on the way.
Merge a description split over files
bundle prints one document. Each $ref to another file becomes a component, named after the file.
The version stays the one the description is written in.
cargo honig bundle openapi.yaml > bundled.json
A $ref: order.yaml becomes $ref: '#/components/schemas/order'. Component names and $refs stay, so other tools such as TypeScript generators and API reference pages read the same document. --format yaml prints it as YAML.