Skip to content
All projects
Backend & APIOpen source

Ferivonus Swagger Gen: Zero-Boilerplate OpenAPI Macro Engine

A zero-boilerplate OpenAPI 3.0.0 generator and custom Swagger UI engine for Actix-Web, distributed as a native Cargo crate and powered by compile-time procedural macros.

View liveSource code

Tech stack

Performance & metrics

  • Absolute zero runtime overhead for reflection; all AST parsing and metadata extraction rigidly occur at compile-time
  • The JSON schema tree is compiled exactly once during server initialization and cached in a Mutex, eliminating per-request parsing latency
  • The UI and documentation payloads are statically embedded directly into the compiled library binary, bypassing file I/O operations entirely

Why I built it

Mainstream Rust OpenAPI crates (like utoipa) introduce significant boilerplate, demanding excessive trait implementations and macro configurations that clutter the codebase. To eliminate this friction, I engineered a bespoke proc-macro engine that parses the AST and automatically collects distributed route/schema definitions at compile-time. I published this engine on crates.io to provide a drop-in dependency that allows other engineers to instantly spin up highly optimized, tabbed Swagger UI interfaces with absolute minimal configuration.

Architecture & decisions

The core operates on the proc-macro layer, utilizing syn and quote to deeply parse the Rust Abstract Syntax Tree (AST). Macros (#[register_api] and #[derive(ApiSchema)]) statically submit structural metadata via inventory::submit!. During Actix-Web runtime initialization, ApiRegistry::new() iterates over the globally collected statics and compiles them into a structured OpenAPI 3.0.0 JSON payload. The presentation layer serves an embedded HTML payload that dynamically injects a custom React hook (TabbedResponsesPlugin) into the SwaggerUIBundle, actively overriding the default DOM representation of HTTP responses.

Key features

  1. 01Packaged and published as a fully isolated, drop-in Cargo crate dependency
  2. 02Recursive AST type lexing for nested Rust generics (Option, Vec, Uuid, DateTime mapping natively to OpenAPI schemas)
  3. 03Autonomous, decentralized route and schema registration via the inventory crate, bypassing central boilerplate constraints
  4. 04Seamless, one-line Actix-Web web::ServiceConfig middleware integration
  5. 05Custom Tabbed HTTP Status UI plugin that hooks directly into the Swagger UI React component tree at runtime

Technical review

This tool demonstrates a highly automated, low-level approach to API contract generation. Its availability on crates.io signifies a mature, production-ready distribution pipeline. The integrated AST parsing mechanism features a recursive lexer (parse_type) capable of deconstructing deeply nested generics (e.g., Vec<Option<Uuid>>) into precise OpenAPI $ref pointers. This strict, proc-macro-driven architecture completely eliminates manual DTO documentation overhead, enforcing absolute synchronization between the underlying Rust memory layout and the exposed external API contract.