Code Generation & Style

Understanding the procedural code generation pipeline and the `openapi` CLI tool.

The vast majority of this library is procedurally generated from the official Stripe OpenAPI specification. This ensures 100% field accuracy, correct types, and up-to-date coverage with Stripe's rapid API evolution.

The Generator CLI

The code generation logic resides in the openapi crate. It is a standalone Rust CLI tool used to fetch specifications, analyze dependencies, and generate the library code.

Running the Generator

To update the library to the latest Stripe API version, run the generator from the openapi directory:

cd openapi
# Fetches the latest spec from GitHub and regenerates code
cargo run --release -- --fetch latest

CLI Arguments

The generator (openapi/src/main.rs) supports several flags to control the build process:

Argument	Description
`--fetch <VERSION>`	Fetches a specific OpenAPI spec version. Options: `latest` (from GitHub releases), `current` (defined in `version.json`), or specific tags like `v171`.
`--spec-path <PATH>`	Input path for the OpenAPI JSON spec. Defaults to `spec3.sdk.json`.
`--out <DIR>`	Output directory for generated code. Defaults to `out`. The tool automatically copies valid output to `generated/`.
`--graph`	Generates dependency graphs in DOT format (`graphs/crate_graph.txt`, `graphs/components_graph.txt`) to aid in debugging cyclic dependencies.
`--dry-run`	Runs generation logic without copying files to the final `generated/` destination.

Architecture & Workflow

To manage the complexity of the Stripe API, the generator performs several optimization passes:

Fetching & Parsing: Downloads spec3.sdk.json and parses thousands of schema definitions.
Dependency Analysis: Builds a directed graph of all Stripe objects to identify dependencies between resources.
Crate Splitting: Uses gen_crates.toml configuration to group resources into modular crates (e.g., stripe-billing, stripe-connect).
Cycle Breaking: Identifies cyclic dependencies (e.g., a Customer has a Subscription, a Subscription has a Customer) and extracts shared types into the async-stripe-types crate to resolve them.
Rendering: Outputs strongly-typed Rust structs, enums, and builder methods using miniserde for fast compilation.

Configuration (gen_crates.toml)

The mapping of Stripe resources to Rust crates is defined in openapi/gen_crates.toml. This file controls the modular structure of the library and ensures related resources are bundled together.

# Example from gen_crates.toml
[[crates]]
name = "billing"
packages = ["test_helpers", "billing_portal", "billing"]
paths = [
    "credit_note",
    "tax_id",
    "invoice",
    # ...
]
description = "This crate provides Rust bindings to the Stripe HTTP API..."

Manual Extensions

Because generated code is overwritten on every update, we strictly separate manual logic from generated logic.

Generated Code: Lives in generated/*. This code is never edited manually.
Extensions: Hand-written logic lives in _ext.rs files inside the resource crates or async-stripe-types. This allows us to add convenience methods (like currency helpers or custom serialization logic) without conflicting with the autogenerated structs.