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

Settings

cargo honig init openapi.yaml writes the module api with the settings that most crates change. Here the crate depends on reqwest and uuid:

[dependencies]
honig = { version = "=0.0.1", features = ["simd"] }

[package.metadata.honig.api]
spec = "openapi.yaml"
client = { adapters = ["reqwest"] }
server = true
formats = { uuid = true }

Each table [package.metadata.honig.<module>] is one module and sets what is generated into it. These are all its settings:

SettingRequiredDefaultWhat it does
specyesthe description relative to Cargo.toml; a list [“a.yaml”, “api/*.yaml”] merges several
outputno"src/<module>"the module directory
clientnotruegenerate the client; a table sets its adapters = [“reqwest”] and operations = [“getOrder”]
servernotruegenerate the server; a table sets its adapters = [“axum”] and allow_unimplemented = true
testsnofalsegenerate a test that the description’s examples decode
unknown_fieldsno"drop"“keep”: objects without additionalProperties keep unknown keys
overlaysno[]Overlays (1.0 to 1.2) applied in order to the spec
formatsnothe dependencieslibrary types of string formats, like { uuid = true, dates = “chrono” }
derivesno{}extra derives on every type or on one type by Rust name, like { “*” = [“Hash”] }

Client and server

client and server are each true, false or a table that turns the half on with settings of its own:

ValueWhat is generatedRuntime features
client = falseno clientnone for the client
client = truethe client; you bring a transport of your ownclient
client = { adapters = ["reqwest"] }the client and ReqwestTransportclient, reqwest
client = { adapters = ["reqwest"], operations = ["getOrder"] }the client with one operationclient, reqwest
server = { adapters = ["axum", "tracing"] }the server, into_axum and a span per requestserver, axum, tracing
server = { allow_unimplemented = true }the server; a method you do not write answers 501server

An adapter serves one half, and tracing-opentelemetry serves both. Each adapter needs its library in [dependencies]. Adapters lists them all.

Several root documents

Some APIs describe themselves in many complete documents. Matrix has one per area. List them, with * for the files of a directory:

[package.metadata.honig.api]
spec = ["matrix/client-server/*.yaml"]

Each file is bundled against its own directory and upgraded to 3.2 alone. Then paths, webhooks, components and tags merge into one module.

  • Files whose one server differs only in its path share the host. Each file’s base path moves into its paths (/login under /_matrix/client/v3 is /_matrix/client/v3/login). The client’s base URL then serves every operation.
  • Files on different hosts keep their servers on their path items.
  • One method of one path in two files is an error. So is one component name with two different values.

Overlays apply to the merged document.

Overlays

Overlays fix a description that you do not own without editing it. List Overlays here. They apply in order to the description as written. This happens before $refs are bundled.

[package.metadata.honig.api]
spec = "vendor/openapi.yaml"
overlays = ["public.overlay.yaml"]
overlay: 1.2.0
info: {title: Public operations, version: "1"}
actions:
  - target: $.paths['/internal']
    remove: true
  - target: $.paths['/products'].get
    update: {operationId: listProducts}

honig reads Overlay 1.0 to 1.2 with every action. That is update, remove, copy and the reusable actions under components.actions. Targets are RFC 9535 JSONPath.

honig reports a broken action with its index and skips it. The others still apply. cargo honig check reads the overlays too. A changed overlay makes the module stale.

Several APIs in one crate

A crate often serves its own API and calls others. Add a table per module:

[package.metadata.honig.api]
spec = "own.yaml"
client = false

[package.metadata.honig.billing]
spec = "vendor/billing.yaml"
server = false
client = { operations = ["createInvoice", "getInvoice"] }

Then declare each module: mod api; and mod billing;.

  • The table name is the module name. It must be a Rust identifier and not a keyword.
  • The generated code of a module depends only on its description and its table.
  • The runtime features are the union of what every module needs. One module with XML bodies turns on xml for the crate.
  • Each module holds its own types. Identical schemas in two descriptions are two types, so the APIs can change apart. Convert between them with From impls.

cargo honig generate writes every module. cargo honig generate billing writes one, and Cargo.toml keeps the features of all of them. check and validate take a module name the same way.

Workspaces

Each member keeps its own [package.metadata.honig.<module>]. Run the commands in the member, or at the workspace root:

  • cargo honig generate at a virtual workspace root runs for every member with module tables. check does too.
  • cargo honig generate -p shop runs for the member shop only. cargo honig generate billing runs for each member with the module billing.
  • A member with honig = { workspace = true } lists its features. generate pins the version in the root’s [workspace.dependencies].