openapi-to-rust

Documentation

Generate a Rust client from OpenAPI

This guide takes an existing OpenAPI document and turns it into typed Rust models plus an async Reqwest client. The same workflow can also generate Axum server scaffolding.

Last reviewed July 15, 2026

On This Page
  1. Requirements
  2. Install
  3. Generate code
  4. Generated files
  5. Configuration
  6. Use it in CI
  7. Next steps

Requirements

You need a Rust toolchain with Rust 1.88 or newer and an OpenAPI 3.0 or 3.1 document in YAML or JSON. Experimental OpenAPI 3.2 parsing is available, but you should review theschema support notes before relying on newer fields.

Direction matters

openapi-to-rust is spec-first: it generates Rust from an existing OpenAPI contract. If you want to generate an OpenAPI document from Rust source, use a code-first library such as Utoipa or Aide instead.

Install the Cargo CLI

Install the published crate with its lockfile so Cargo uses the dependency versions tested for the release:

Terminalshell
cargo install --locked openapi-to-rust
openapi-to-rust --version

Cargo compiles the CLI locally. There are currently no prebuilt binaries, so a working Rust toolchain is required. You do not need Java, Node.js, or Docker to run the generator.

Generate code from an OpenAPI document

For a quick trial, generate from the project’s stable hosted fixture:

Terminalshell
openapi-to-rust generate \
  https://raw.githubusercontent.com/gpu-cli/openapi-to-rust/v0.6.0/tests/fixtures/operation_extraction/simple_get.json

For your own project, pass a local YAML or JSON file:

Terminalshell
openapi-to-rust generate openapi.yaml

The async client is generated by default. Use --types-only if you only need Serde models,--dry-run to inspect the generation plan without writing, or --check to detect stale output.

Understand the generated files

The default command writes a self-contained module under src/generated:

Default generated Rust output
FilePurpose
types.rsSerde structs and enums derived from schemas and inline operation types.
client.rsAsync Reqwest methods, request serialization, auth hooks, and typed operation errors.
mod.rsModule exports for the generated surface.
REQUIRED_DEPS.tomlThe exact dependencies needed to compile this particular output.

Streaming or server files appear only when those features are configured. Generated output is designed to be committed so application builds do not need to fetch the API document or execute code generation.

Create a reusable configuration

Initialize a TOML file, then generate using its defaults:

Terminalshell
openapi-to-rust init openapi.yaml
openapi-to-rust generate

openapi-to-rust.tomltoml
[generator]
spec_path = "openapi.yaml"
output_dir = "src/generated"
module_name = "api"

[features]
enable_async_client = true

[http_client]
base_url = "https://api.example.com"
timeout_seconds = 30

Relative paths are resolved from the TOML file rather than the shell’s working directory. That makes the same command reliable from a developer laptop, a workspace root, or CI.

HTTPS documents are supported directly. Remote fetches reject embedded credentials and redirects, enforce time and size limits, and allow plain HTTP only for loopback development. For reproducible releases, prefer a versioned URL or a checked-in document.

Keep generated Rust current in CI

Commit the generated module and add a check that reruns analysis without overwriting files. A non-zero exit tells you the OpenAPI document, configuration, or generated Rust has drifted.

CIshell
openapi-to-rust generate --check --quiet
cargo check

--check verifies freshness. It does not replace cargo check, which proves that the generated module compiles with your project’s dependency choices.

Choose your next path