Skip to main content

Module paths

oapi_codegen::lower

Module paths 

Source
Expand description

Lowering OpenAPI paths/operations into the server crate::ir::Service.

Each operation is lowered into typed inputs (path/query/header parameters and a JSON request body) plus a response enum. The generator only models what it can translate faithfully. Anything else is rejected with an error rather than mis-generated.

Supported:

  • Path parameters — inline scalars, or a same-document $ref to a scalar.
  • Query parameters — scalars and arrays of scalars, lowered into a per-operation Deserialize struct extracted via axum_extra::extract::Query. Required parameters stay bare. optional ones become Option<..>. Arrays must use the default form/explode: true encoding (repeated keys).
  • Header parameters — scalars only, lowered into a per-operation struct extracted via a generated FromRequestParts impl. The reserved Accept/Content-Type/Authorization headers are ignored.
  • Cookie parameters — scalars only, lowered into a per-operation struct extracted via a generated FromRequestParts impl backed by axum_extra’s CookieJar.
  • Component $ref parameters and request bodies — $refs to #/components/parameters/* and #/components/requestBodies/* are resolved against the document.
  • Responses — explicit status codes, the default catch-all, and ranges (5XX). Component $ref responses are resolved against the document.
  • Cross-file $ref parameters, request bodies, and responses — the referenced structural object is read from the sibling file (resolved relative to the main spec’s directory), following chains across files. Parameter inner schemas must still resolve to scalars. body/response inner schema $refs route through the import-mapping to an external type (they are never inlined).

Rejected: object or other non-scalar parameters, non-default query-array encodings, content parameters, array or byte/binary header parameters, byte/binary cookie parameters, path-item $refs, cross-file schema-type $refs (in a body or response) that lack an import-mapping entry for the referenced file, and an unrecognised response status code.

Functions§

generate_service
Lower every operation in spec into the server IR, resolving cross-file schema references through import_mapping. response_type_suffix is appended to each operation’s response-enum name.