reflectapi is a library and a toolkit for writing web API services in Rust and generating compatible clients, delivering great development experience and efficiency.

Features

• Code-first definition of services with API over HTTP
• 100% compatible type-safe and extensible clients delivering same simplicity and intent of the server API
• Multi-language client generation:
  • TypeScript - stable
  • Rust - stable
  • Python - experimental
• Documentation rendering using Redoc tool
• Web framework agnostic with plugable Axum support included, other frameworks are possible
• Full support for all serde attributes
• Full enablement for all Rust types, including standard library, common popular crates and adding support for 3rd party and custom types is straightforward

Documentation

• Crates.io - Package information and versions
• API Documentation - Complete API reference
• User Guide - Tutorials and examples (build locally with mdbook serve in docs/)
• Architecture - System design and internals
• Enum evolution - Declared fallbacks and open response enums

Development notes

Building and running

Ensure that you have prettier, rustfmt, and ruff available in your PATH for consistently formatted generated code.

To run the demo server:

cargo run --bin reflectapi-demo

To generate client in Typescript for demo server:

cargo run --bin reflectapi -- codegen --language typescript --schema reflectapi-demo/reflectapi.json --output reflectapi-demo/clients/typescript

To run the Typescript generated client. Note: requires the demo server running

cd reflectapi-demo/clients/typescript/
npm install
npm run start

To generate client in Rust for demo server:

cargo run --bin reflectapi -- codegen --language rust --schema reflectapi-demo/reflectapi.json --output reflectapi-demo/clients/rust/generated/src/

To run the Rust generated client. Note: requires the demo server running

cd reflectapi-demo/clients/rust/
cargo run --all-features

To generate client in Python for demo server:

cargo run --bin reflectapi -- codegen --language python --schema reflectapi-demo/reflectapi.json --output reflectapi-demo/clients/python

Updating Snapshots

This project uses insta for snapshot testing to ensure code generation output is correct and stable. When tests fail due to snapshot mismatches:

1. Review the changes first to ensure they are expected
2. Update snapshots using one of these commands:

# Interactive review (recommended)
cargo insta review

# Auto-accept all changes (use with caution)
cargo insta accept

3. Re-run tests to verify they pass:

cargo test

Building Documentation

# Install required tools (one-time setup)
cargo install mdbook mdbook-keeper

# Build documentation
cd docs
mdbook build

# Serve documentation locally
mdbook serve  # Opens at http://localhost:3000

# Note: mdbook-keeper automatically runs doctests during build
# The build command both generates HTML and tests code examples

Releasing

Pushing a v* tag triggers .github/workflows/release.yml, which:

1. Requires successful CI on a push to main for the exact tagged commit, verifies every published package version and internal dependency version matches the tag, and extracts a nonempty matching section from CHANGELOG.md (packaging.version parses both Cargo SemVer and PEP 440 forms).
2. Packages and verifies all four Rust crates with the locked dependencies and all features, and builds the pure-Python reflectapi-runtime sdist and wheel before either registry publishes.
3. Publishes the four Rust crates to crates.io in dependency order — reflectapi-schema → reflectapi-derive → reflectapi → reflectapi-cli — using crates.io Trusted Publishing (OIDC, no CARGO_REGISTRY_TOKEN secret), and publishes the Python runtime via PyPI Trusted Publishing. Cargo verifies each crate before publishing.
4. Cuts a GitHub Release with the curated changelog section; pre-release versions are flagged automatically.

Both publishers run inside the release GitHub Environment, which is configured as a trusted publisher on each crate (crates.io) and on the reflectapi-runtime PyPI project.

To prepare a release, bump every version in lockstep, update the internal Cargo dependency versions and lockfiles, and move the release notes under a matching ## <version> heading in CHANGELOG.md. The Cargo files use SemVer (0.18.0-alpha.1), reflectapi-python-runtime/pyproject.toml and src/reflectapi_runtime/__init__.py use PEP 440 (0.18.0a1):

# 1. Bump Cargo SemVer in all four crates.
cargo release \
    --exclude reflectapi-demo \
    --exclude reflectapi-demo-client \
    --exclude reflectapi-demo-client-generated \
    minor --execute --no-publish --no-tag

# 2. Bump the Python runtime (PEP 440 form) by hand:
#    reflectapi-python-runtime/pyproject.toml         version = "..."
#    reflectapi-python-runtime/src/reflectapi_runtime/__init__.py  __version__ = "..."

# 3. Verify every publishable crate, using Cargo's staged workspace registry:
cargo package --workspace --all-features --locked --allow-dirty \
    --exclude reflectapi-demo \
    --exclude reflectapi-demo-client \
    --exclude reflectapi-demo-client-generated

# 4. Commit and land the release preparation on main:
git commit -am "chore: <version>"

# 5. Wait for successful CI on the exact main commit to release.
#    Then, once publishing is approved, tag that commit and push the tag:
git tag v<version>          # the `v` prefix is required
git push origin v<version>

For pre-releases use --prerelease alpha (or beta / rc) on cargo release; the Python equivalent is 0.18.0a1, 0.18.0b1, 0.18.0rc1.