Paperclip

Paperclip is an OpenAPI tooling library for Rust that helps you build type-safe, compile-time checked HTTP APIs. Its actix-web plugin derives an OpenAPI v2/v3 specification directly from your handlers and models, so your documentation stays in lockstep with your code.

Beyond spec hosting, Paperclip provides code generation for efficient clients, servers, and CLIs from an OpenAPI definition, along with utilities for processing and validating specs. It is organized as a workspace of crates — core, macros, the actix-web plugin, and a next-generation CLI generator — that you compose through feature flags.

What You Get

• An actix-web plugin that derives OpenAPI v2/v3 specs from handlers and models
• Derive macros (Apiv2Schema and friends) for annotating request/response types
• Code generation for type-safe HTTP clients, servers, and CLIs from a spec
• A paperclip binary (behind the cli feature) plus a next-gen cli-ng generator
• Core utilities for parsing, validating, and hosting OpenAPI specifications

Common Use Cases

• Auto-generating an always-accurate OpenAPI spec from an actix-web service
• Generating a type-safe Rust client from a third-party OpenAPI definition
• Serving interactive API documentation derived from your Rust code

Under The Hood

Architecture — Paperclip is a Cargo workspace. The root paperclip crate (src/lib.rs, src/v2/) is a thin umbrella that re-exports functionality from member crates behind feature flags: core/ holds the OpenAPI data model and validation, macros/ provides the derive macros used to annotate types, plugins/actix-web/ implements the actix integration that collects schema information at compile time, and cli-ng/ is a newer generator. A paperclip binary (src/bin/main.rs) is built only with the cli feature. Mustache and Handlebars templates drive code generation.

Tech Stack — Rust (edition 2018) built on serde/serde_json/serde_yaml for spec handling, semver, itertools, and url; optional dependencies include structopt for the CLI, reqwest and git2 for fetching specs, heck and tinytemplate/Handlebars for code generation, and the actix-web ecosystem for the plugin. Everything non-core is gated behind feature flags.

Code Quality — A mature project with 66 contributors, 21 releases, an mdBook guide, and a tests/ suite covering the plugin and generation paths. The workspace separation keeps the core model, macros, and framework glue cleanly decoupled. The README notes it is still under active development and not yet declared production-ready.

API Design — For actix users the ergonomics are strong: derive Apiv2Schema on your types, wrap the app, and the spec is produced with minimal boilerplate. The breadth of feature flags and the split between the legacy generator and cli-ng add some surface area to learn, but the common actix path is well documented in the book and examples.