reflectapi-schema 0.16.4

A library for defining and serializing/deserializing ReflectAPI schemas
Documentation

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

Development notes

Building and running

Ensure that you have prettier and rustfmt available in your PATH to format 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
  1. 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

cargo release --exclude reflectapi-demo --exclude reflectapi-demo-client --exclude reflectapi-demo-client-generated minor --execute