If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/juhaku/utoipa shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3d ago
• 34+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live juhaku/utoipa repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/juhaku/utoipa.

What it runs against: a local clone of juhaku/utoipa — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in juhaku/utoipa | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of juhaku/utoipa. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/juhaku/utoipa.git
#   cd utoipa
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of juhaku/utoipa and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "juhaku/utoipa(\\.git)?\\b" \\
  && ok "origin remote is juhaku/utoipa" \\
  || miss "origin remote is not juhaku/utoipa (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "utoipa/Cargo.toml" \\
  && ok "utoipa/Cargo.toml" \\
  || miss "missing critical file: utoipa/Cargo.toml"
test -f "utoipa-gen/Cargo.toml" \\
  && ok "utoipa-gen/Cargo.toml" \\
  || miss "missing critical file: utoipa-gen/Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "examples/todo-actix/src/main.rs" \\
  && ok "examples/todo-actix/src/main.rs" \\
  || miss "missing critical file: examples/todo-actix/src/main.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/juhaku/utoipa"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

utoipa is a Rust crate that auto-generates OpenAPI 3.0+ documentation at compile-time from annotated code using procedural macros, eliminating manual YAML/JSON specification writing. It provides both macro-based code-first documentation and native Rust types to represent the entire OpenAPI spec, integrating seamlessly with web frameworks like Actix-web, Axum, and Rocket. Monorepo with 10 workspace members: core utoipa crate provides macros and OpenAPI types; utoipa-gen contains code generation logic; framework-specific integration crates (utoipa-actix-web, utoipa-axum) wrap functionality; UI crates (utoipa-swagger-ui, utoipa-redoc, utoipa-scalar, utoipa-rapidoc) handle documentation rendering; examples/ directory contains 40+ runnable demonstrations for each framework+feature combination.

Rust backend developers building REST APIs who want production-ready OpenAPI documentation without maintaining separate spec files; framework integration maintainers (Actix, Axum, Rocket) who need to expose bindings; teams adopting code-first API design patterns in the Rust ecosystem.

Production-ready and actively maintained. The project shows strong maturity with MSRV pinned to 1.75, published on crates.io with consistent versioning (badge visible), organized GitHub Actions CI/CD pipeline (build.yaml, release.yaml, draft.yaml), and a monorepo structure with 10 member crates. Last observable structure shows recent refinement with vendored UI dependencies and multiple framework integrations.

Standard open source risks apply.

Active maintenance evident from multiple release workflows and draft release tracking (.github/workflows/release.yaml, draft.yaml). Recent work includes multi-framework example expansion (axum-multipart, actix-web-multipart, generics examples) and vendored UI dependency management. No specific breaking changes visible, suggesting stability focus.

git clone https://github.com/juhaku/utoipa.git
cd utoipa
cargo build
cargo test
# Run a specific example:
cd examples/axum-utoipa-bindings
cargo run

Daily commands: No single 'dev server'—framework-specific examples run independently. Example: cd examples/axum-utoipa-bindings && cargo run starts an Axum server with Swagger UI at localhost. For macro testing: cargo test -p utoipa-gen runs proc-macro unit tests.

• Cargo.toml — Workspace manifest defining all member crates and their publishing order; essential to understand the monorepo structure and dependency resolution.
• utoipa/Cargo.toml — Core library manifest; declares the main OpenAPI code-generation and schema derivation framework.
• utoipa-gen/Cargo.toml — Procedural macro crate for compile-time code generation; critical for understanding how the derive macros and attribute macros work.
• README.md — High-level overview of project scope, capabilities, and design philosophy; must-read for understanding what utoipa is and isn't.
• examples/todo-actix/src/main.rs — Representative example demonstrating the canonical patterns for integrating utoipa with a web framework and generating OpenAPI docs.
• utoipa-axum/Cargo.toml — Bindings crate for Axum framework; shows how utoipa extends to framework-specific integrations.
• CHANGELOG.md — Version history and breaking changes; critical for understanding API evolution and compatibility constraints.

Add support for a new web framework

1. Create a new integration crate following the pattern of utoipa-axum or utoipa-actix-web (e.g., utoipa-warp/Cargo.toml) (utoipa-warp/Cargo.toml)
2. Implement framework-specific extractors or middleware that implement utoipa's traits (e.g., IntoParams, IntoResponses) (utoipa-warp/src/lib.rs)
3. Add an example application demonstrating the framework integration following the structure of existing examples (examples/todo-warp/src/main.rs)
4. Register the new crate as a member in the workspace Cargo.toml and add it to the publish order in metadata (Cargo.toml)

Add a new custom OpenAPI schema type or format

1. Define the schema type by implementing utoipa's trait (likely ToSchema or similar) in a crate under utoipa or utoipa-gen (utoipa/src/lib.rs)
2. Add procedural macro support in utoipa-gen if compile-time code generation is needed (utoipa-gen/src/lib.rs)
3. Add tests and documentation examples demonstrating the new schema type (examples/generics-actix/src/main.rs)

Add a new UI rendering backend (like Swagger UI, ReDoc, etc.)

1. Create a new crate following the pattern of utoipa-redoc or utoipa-rapidoc (e.g., utoipa-my-ui/Cargo.toml) (utoipa-redoc/Cargo.toml)
2. Implement the web framework handlers or middleware to serve the UI with the OpenAPI spec (inspect existing UI crates for patterns) (utoipa-redoc/src/lib.rs)
3. Create an example application demonstrating the new UI backend (examples/simple-axum/src/main.rs)
4. Register the crate in the workspace Cargo.toml and add to publish order (Cargo.toml)

Extend OpenAPI documentation for an endpoint with custom attributes or x-extensions

1. Add custom derive macro attributes or parameters to your endpoint handler struct/function to capture additional metadata (examples/simple-x-extensions/src/main.rs)
2. Use builder methods on Operation, Schema, or OpenApi to inject x-extensions or custom fields before serialization (utoipa/src/lib.rs)
3. Verify the custom fields appear in the generated OpenAPI JSON output by testing or viewing the spec in a UI server (examples/simple-x-extensions/src/main.rs)

• Procedural Macros (utoipa-gen) — Enables compile-time code generation to extract type information and automatically derive OpenAPI schemas, eliminating runtime reflection overhead and ensuring type safety.
• serde for serialization — Provides battle-tested JSON/YAML serialization of the OpenAPI spec; integrates naturally with derive macros and ecosystem conventions.
• Vendored Swagger UI (swagger-ui-vendored) — Avoids external CDN dependencies and network calls; enables offline documentation serving and reduces deployment complexity.
• Framework integration crates (axum, actix-web) — Provides framework-specific extractors and type conversions to reduce boilerplate and enable automatic schema inference from handler signatures.
• Monorepo (Cargo workspace) — Allows separation of concerns (core schema, framework integrations, UI backends) while maintaining atomic versioning and coordinated releases.

• Compile-time code generation via procedural macros

  • Why: Maximizes type safety and eliminates runtime reflection; provides zero-cost abstractions and improved build clarity.
  • Consequence: Increases compile time; requires careful macro error messages for user experience; couples tightly to Rust compiler versions.

• Framework-specific integration crates rather than runtime dispatcher

  • Why: Enables idiomatic and zero-overhead integration for each framework; avoids dynamic dispatch overhead.
  • Consequence: Requires separate maintenance per framework; developers must choose the appropriate utoipa crate; reduces portability across frameworks.

• Vendored UI assets (Swagger, ReDoc, RapiDoc, Scalar)

  • Why: Simplifies deployment; avoids external CDN dependencies and network latency; supports offline usage.
  • Consequence: Increases binary/artifact size; UI frameworks are static and cannot be easily updated without crate updates; multiple UI options increase maintenance burden.

• Code-first (derive macros) rather than spec-first

  • Why: Keeps documentation alongside code; eliminates manual spec synchronization; enables type checking of schemas.
  • Consequence: Spec becomes secondary to code; developers less familiar with OpenAPI spec semantics; harder to serve as a contract without proper CI validation.

• Runtime dynamic OpenAPI spec generation based on reflection or configuration

Proc-macro crate coupling: utoipa-gen must be compiled before utoipa in dependency order—check workspace.metadata.publish order if experiencing build failures. MSRV constraint: Rust 1.75+ required; older toolchains will fail silently on nightly features in syn/quote. Macro hygiene: derive macros may conflict with other derive macros (serde, etc.) if field attributes collide—use fully-qualified paths in edge cases. Feature flags matter: ui features (swagger-ui, redoc, scalar) are optional; examples assume they're enabled. Path vendor quirk: utoipa-swagger-ui-vendored checks at build-time for bundled assets—build in repo root, not subdirectory.

• Procedural Macros (derive & attribute) — utoipa's core mechanism—#[derive(ToSchema)] and #[openapi] are proc-macros that parse Rust code at compile time, not runtime, enabling zero-cost abstraction and static type checking of OpenAPI specs
• Code-First API Design — Opposite of spec-first (write YAML, generate stubs); utoipa enforces code as source-of-truth, generating docs from compiled Rust types, reducing documentation drift
• OpenAPI 3.0+ Specification — utoipa generates OpenAPI 3.0.x-compatible JSON/YAML schemas; understanding the spec (operations, components, paths, schemas) is essential for customizing generated documentation
• Trait-Based Schema Generation (ToSchema, IntoParams, IntoResponse) — utoipa uses Rust trait derivation to encode type metadata; implementing these traits tells utoipa how to represent your types in OpenAPI—critical for custom types or generics
• Monorepo with Workspace Publishing — utoipa coordinates 10+ crates with explicit dependency order (utoipa-config→utoipa-gen→utoipa); workspace build and publish must respect this DAG to prevent circular/missing dependencies
• Vendored Assets (JavaScript/CSS bundling) — utoipa-swagger-ui-vendored packages Swagger UI as Rust byte arrays; avoids CDN dependencies at runtime and enables offline-first documentation serving, critical for enterprise security
• Generic Type Parameter Serialization — utoipa must encode Rust generics (e.g., Result<T, E>, Option<User>) into concrete OpenAPI schemas; examples/generics-actix demonstrates how trait bounds and type parameters are resolved

• paperclip-rs/paperclip — Alternative compile-time OpenAPI generator for Rust using different macro approach; direct competitor for code-first API documentation
• tokio-rs/axum — Primary web framework utoipa integrates with; utoipa-axum provides extension macros for Axum routers
• actix/actix-web — Major web framework with deep utoipa integration via utoipa-actix-web; widely-used alternative to Axum in Rust
• serde-rs/serde — Serialization framework that utoipa relies on for schema derivation via serde attributes (container/field-level metadata)
• dtolnay/syn — Rust AST parsing library utoipa-gen uses internally for proc-macro implementation; critical dependency for macro reliability

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for multi-workspace crate publishing order

The workspace defines a strict publish order in [workspace.metadata.publish] with 10 crates. However, there are no visible integration tests verifying this order is correct or that version dependencies between crates are properly maintained. A new contributor could add tests in .github/workflows or a new test suite that validates: (1) each crate's Cargo.toml dependencies reference correct versions of other workspace members, (2) the publish order respects dependency chains, and (3) a dry-run publish would succeed. This prevents dependency resolution failures during release.

• [ ] Create tests/publishing_order_validation.rs to parse Cargo.toml files from all workspace members
• [ ] Validate dependency versions match workspace member versions in publish order sequence
• [ ] Add a GitHub Actions workflow step in .github/workflows/release.yaml to run these tests before publishing
• [ ] Document the validation logic in a new CONTRIBUTING.md section for maintainers

Add missing README files and getting-started docs for workspace crates

While examples/ has READMEs and the root README exists, the individual workspace crates (utoipa, utoipa-gen, utoipa-swagger-ui, utoipa-redoc, utoipa-rapidoc, utoipa-scalar, utoipa-axum, utoipa-config, utoipa-actix-web) listed in Cargo.toml members appear to lack dedicated README files in their respective directories. New contributors could create feature-specific READMEs explaining when to use each crate, basic setup, and feature flags.

• [ ] Create utoipa/README.md with core features, basic example, and feature flag documentation
• [ ] Create utoipa-gen/README.md explaining code generation and macro usage
• [ ] Create utoipa-axum/README.md and utoipa-actix-web/README.md with framework-specific integration guides
• [ ] Create utoipa-swagger-ui/README.md, utoipa-redoc/README.md, utoipa-rapidoc/README.md, and utoipa-scalar/README.md documenting UI crate choices and differences
• [ ] Link these from the root README.md in a 'Workspace Crates' section

Add MSRV (Minimum Supported Rust Version) validation to CI

Cargo.toml defines [workspace.package] rust-version = "1.75", but there's no CI job verifying builds actually succeed on MSRV. The build.yaml workflow likely uses stable or latest. A new contributor could add a dedicated CI job that tests compilation against Rust 1.75 to prevent accidental use of newer language features, following Rust ecosystem best practices.

• [ ] Add a new job 'test-msrv' to .github/workflows/build.yaml after the main test job
• [ ] Use actions-rs/toolchain@v1 to install Rust 1.75 specifically
• [ ] Run 'cargo +1.75 build --workspace' and 'cargo +1.75 test --workspace' for each member
• [ ] Ensure all examples also build on MSRV or document minimum version per example
• [ ] Document MSRV policy in CONTRIBUTING.md

• Add #[doc] comment parsing to derive macros: Extend utoipa-gen/src/ to parse Rust doc comments on struct fields and use them to auto-populate OpenAPI descriptions without requiring #[doc = "..."] attributes
• Create integration test suite for framework compatibility: Add tests/ directory with cross-framework integration tests verifying that identical API definitions generate identical OpenAPI JSON across utoipa-actix-web, utoipa-axum, and utoipa-rocket
• Expand examples for edge cases: Add examples/ entry for polymorphic responses (OneOf), request/response middleware, and custom content-type handling currently not demonstrated (check examples/ against OpenAPI 3.1 spec)

The utoipa repository demonstrates generally good security hygiene as a code-first OpenAPI documentation library. No critical vulnerabilities or hardcoded secrets were identified in the visible file structure. The main concerns are operational: lack of formal security disclosure policy, absence of explicit dependency vulnerability scanning integration, and general security documentation for examples. The library's focus on compile-time code generation inherently mitigates runtime injection attacks. Recommendations focus on improving security transparency and establishing formal vulnerability reporting procedures. No SQL injection, XSS, or infrastructure misconfigurations were detected in the provided structure. Regular dependency audits via cargo-audit and formal security governance would further strengthen the security posture.

• Medium · Workspace-wide Rust version constraint — Cargo.toml (workspace.package.rust-version). The workspace specifies rust-version = 1.75, which is relatively recent. However, MSRV (Minimum Supported Rust Version) policies should be regularly reviewed and updated. Using an older MSRV than necessary may expose the crate to known vulnerabilities in the Rust compiler/standard library. Fix: Regularly audit and update the MSRV to a version that balances compatibility with security patches. Document the MSRV rationale in the README.
• Low · Missing security.txt policy file — Repository root. No visible security policy or vulnerability disclosure procedure (SECURITY.md or similar) found in the root directory. This makes it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file following RFC 9116 standards with instructions for responsible vulnerability disclosure and security contact information.
• Low · Lack of dependency pinning in workspace — Cargo.toml (workspace configuration). The Cargo.toml workspace configuration doesn't show explicit dependency specifications. Without proper version constraints, transitive dependencies could introduce vulnerabilities during updates. Fix: Review all direct dependencies and implement appropriate version constraints. Consider using 'cargo-audit' in CI/CD pipeline to detect known vulnerabilities in dependencies. Document dependency policy.
• Low · Multiple examples with potential configuration exposure — examples/ directory. The examples directory contains multiple web framework examples (actix, axum, rocket, warp, tide) without visible input validation patterns shown. Examples often serve as templates for real applications. Fix: Audit example code for secure coding practices. Add security-focused examples demonstrating proper input validation, CORS configuration, authentication, and authorization patterns.
• Low · CI/CD workflows visibility — .github/workflows/. GitHub Actions workflows are present (.github/workflows/) but their actual security configuration is not visible. Workflows handling publishing could be vulnerable to supply chain attacks if not properly secured. Fix: Implement GitHub Actions security best practices: use pinned action versions (commit SHAs), implement least-privilege permissions, enable branch protection rules, and audit workflow permissions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.