Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.