https://docs.rs/oas-forge

OpenAPI Specs Forge (oas-forge)

The zero-runtime OpenAPI 3.1 compiler for Rust.

oas-forge extracts, links, and merges code-first documentation into a standard openapi.yaml file at compile time. It eliminates the need for runtime macros that bloat your binary and crash on startup.

🏗️ Architecture

[Source Code] --> [Scanner] --> [AST Parsing] --> [Registry]    
                                                     |
                                                     v
[Static YAML] --> [Merger] <--- [Monomorphizer] <--- [Fragments]
                       |
                       v
                 [openapi.yaml]

---

🛠️ Integration Guide

[build-dependencies]
oas-forge = "0.1"

Method A: build.rs (Fluent API)

use oas_forge::Generator;

println!("cargo:rerun-if-changed=src");
println!("cargo:rerun-if-changed=Cargo.toml");

Generator::new()
    .input("src") // Recursive input directory (where to search for doc comments)
    .input("lib") // Multiple inputs supported
    .include("static/security.yaml") // Merge static oas content - optional
    .include("static/skeleton.json") // Multiple includes supported (yaml and json supported)
    .output("openapi.yaml") // Full Spec (Strict: requires openapi/info root)
    // This is for lib exports to be used in other projects (in .include(...))
    .output_fragments("fragment.json") // Headless Spec (Paths + Components, no Root)
    // More fine-grained outputs (Relaxed: no validation)
    .output_schemas("schemas.json") // Components/Schemas only
    .output_paths("routes.yaml") // Paths only
    .generate()
    .expect("Failed to generate OpenAPI spec");

    // Note: Output file extension determines format (yaml/json)

Method B: Cargo.toml Metadata

Configure in your manifest to keep build.rs minimal.

Cargo.toml:

# Same possibilities as Method A, but configured via Cargo.toml
[package.metadata.oas-forge]
input = ["src", "lib"]
include = ["static/skeleton.yaml"]

# Full Specs
output = ["openapi.yaml"]

# Granular Exports
output_fragments = ["dist/lib-spec.yaml"]
output_schemas = ["frontend/api-types.json"]
output_paths = ["gateway/routes.yaml"]

build.rs:

use oas_forge::{config::Config, Generator};

fn main() {
  println!("cargo:rerun-if-changed=src");
  println!("cargo:rerun-if-changed=Cargo.toml");
  
  let config = Config::load();

  if let Err(e) = Generator::new()
    // Use Cargo.toml metadata
    .with_config(config)
    .generate()
  {
    eprintln!("Warning: Failed to generate OpenAPI docs: {}", e);
  }
}

Method C: CLI

Ideal for CI/CD pipelines.

cargo install oas-forge
# Run generation
oas_forge -i src -o openapi.yaml 
oas_forge -i src -I static/openapi.yaml -o openapi.yaml
oas_forge -i src -i lib -I static/skeleton.yaml -I static/security.json -o openapi.yaml

# You get the idea. More complex example:
oas-forge \
  -i src \
  --output openapi.yaml \
  --output-fragments dist/lib.yaml \
  --output-schemas types.json \
  --output-paths routes.yaml

---

✨ Feature Reference

⚡ Route DSL

The Route DSL allows you to define API operations directly above your handler functions. This avoids verbose YAML and keeps your code clean.

Basic Example

/// List Users
/// 
/// Returns a paginated list of users.
///
/// @route GET /users
/// @tag Users
/// @query-param page: Option<u32> "Page number"
/// @return 200: $Vec<User> "List of users"
async fn list_users() { ... }

Advanced Features

1. Inline Path Parameters Define path parameters, their types, and descriptions directly in the route string.

/// @route GET /users/{id: u32 "The unique ID"}
fn get_user(id: u32) { ... }

• Result: Automatically registers id as in: path, required: true, with schema: {type: integer, format: int32}.

2. Flexible Parameter Syntax Define path, query, header, or cookie parameters (@path-param, @query-param, @header-param, @cookie-param). Attributes like deprecated, required, or example can be placed in any order after the type. Path parameters are name validated against the route path.

/// @route GET /search
/// @query-param filter: Option<String> deprecated example="Alice" "Filter by name"
/// @header-param X-Trace-ID: Uuid required "Tracing ID"
fn search() { ... }

• deprecated: Sets deprecated: true.
• example="Alice": Sets example: "Alice".
• Option<T>: Infers required: false (unless required flag is explicitly present).

3. Smart Responses (@return) The DSL infers schemas and handles generics automatically.

/// @route POST /users
/// @return 201: $User "Created"          <- JSON Ref to User schema
/// @return 200: $Page<User> "List"       <- Monomorphized Generic ($Page<User> -> Page_User)
/// @return 204: "Deleted"                <- Unit Type (No Content body)
/// @return 400: "Invalid Input"          <- String Literal (Description only)
fn create_user() { ... }

4. Request Body (@body) Link a Struct as the request body. Defaults to application/json if no MIME type is specified.

/// @route POST /users
/// @body $CreateRequest application/json
fn create() { ... }

5. Security (@security) Apply security schemes defined in your root spec or fragments.

/// @route GET /protected
/// @security oidc("read", "write")
/// @security basic()
fn protected() { ... }

6. Mixing Raw YAML (Overrides) You can mix standard OpenAPI YAML attributes directly within the DSL block. This is useful for complex scenarios or when using @insert with fragments containing bare YAML keys. Supported top-level keys: parameters, requestBody, responses, security, callbacks, externalDocs, servers.

/// @route GET /complex
/// @tag Items
///
/// # You can inject raw parameters alongside DSL
/// parameters:
///   - name: raw_param
///     in: query
///     schema: { type: string }
///
/// # Or override the description
/// externalDocs:
///   url: https://example.com/docs
///   description: More info
///   description: More info
fn complex_handler() {}

7. Virtual Routes Define routes in module-level documentation (e.g., src/main.rs) without an attached function. Useful for legacy endpoints or proxies.

//! @route GET /legacy/proxy
//! @tag Legacy
//! @return 200: "Proxy Response"

🏛️ Legacy / Manual Mode

You don't have to use the DSL. oas-forge fully supports "Old School" OpenAPI definitions where you simply write raw YAML in your doc comments. This gives you full control.

/// @openapi
/// paths:
///   /manual/endpoint:
///     get:
///       tags: [Manual]
///       summary: Fully manual definition
///       description: This is standard OpenAPI YAML.
///       responses:
///         '200':
///           description: OK
///           content:
///             text/plain:
///               schema: { type: string }
async fn manual_handler() {}

Integration Example: Serving with Axum

Here is a complete pattern for serving your dynamic OpenAPI spec and Swagger UI using axum.

use axum::{
    Router,
    http::header,
    response::{Html, IntoResponse},
    routing::get,
};
use std::env;

// Embed the generated file
const OPENAPI_SPEC: &str = include_str!("../../openapi.yaml");

pub fn router() -> Router {
    Router::new()
        .route("/openapi.yaml", get(serve_spec))
        .route("/swagger", get(serve_ui))
}

/// @openapi
/// paths:
///   /docs/openapi.yaml:
///     get:
///       tags: [System]
///       summary: Get OpenAPI Specification
///       description: Returns the dynamic OpenAPI specification.
///       responses:
///         '200':
///           description: The OpenAPI YAML file.
///           content:
///             application/yaml:
///               schema: { type: string }
async fn serve_spec() -> impl IntoResponse {
    let spec = OPENAPI_SPEC.replace("$$OIDC_URL", &env::var("OIDC_URL").unwrap_or_default());
    ([(header::CONTENT_TYPE, "application/yaml")], spec)
}

async fn serve_ui() -> impl IntoResponse {
    let html = r#"<!DOCTYPE html>
<html lang="en">
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = () => {
      SwaggerUIBundle({
        url: '/docs/openapi.yaml',
        dom_id: '#swagger-ui',
        presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
        layout: "BaseLayout",
      });
    };
  </script>
</body>
</html>"#;
    Html(html)
}

📦 Schema Extraction

Annotate your data structures, enums and types with doc comments to generate OpenAPI schemas.

// Defines a custom PhoneNumber type. (As example for types from other crates.)
//! @openapi-type PhoneNumber
//! type: string
//! format: tel
//! pattern: "^\\+?[1-9]\\d{1,14}$"
//! description: E.164 formatted phone number.
//! example: "+491701234567"

/// E-Mail address.
/// @openapi
/// example: "johnd@mail.com"
/// format: email
pub type Email = String;

/// Description of user roles within the system.
/// @openapi
pub enum Role {
  Admin,
  Moderator,
  User,
}

/// Description of a User entity.
/// @openapi
pub struct User {
  pub id: u32,

  /// The username of the user.
  /// @openapi example: "johndoe"
  pub username: Option<String>,

  /// The email address of the user.
  /// @openapi example: "johndoe@mail.com"
  pub email: Email,

  pub phone: PhoneNumber,

  /// The role assigned to the user.
  /// @openapi default: "User"
  pub role: Role,

  pub is_active: bool,

  /// The timestamp when the user was created.
  /// @openapi example: "2024-01-01T12:00:00"
  pub created_at: chrono::NaiveDateTime,
}

generates:

components:
  schemas:
    PhoneNumber:
      type: string
      format: tel
      pattern: ^\+?[1-9]\d{1,14}$
      description: E.164 formatted phone number.
      example: '+491701234567'
    Role:
      description: Description of user roles within the system.
      enum:
        - Admin
        - Moderator
        - User
      type: string
    Email:
      description: E-Mail address.
      example: johnd@mail.com
      format: email
      type: string
    User:
      description: Description of a User entity.
      properties:
        created_at:
          description: The timestamp when the user was created.
          example: 2024-01-01T12:00:00
          format: date-time
          type: string
        email:
          $ref: '#/components/schemas/Email'
          description: The email address of the user.
          example: johndoe@mail.com
        id:
          format: int32
          type: integer
        is_active:
          type: boolean
        phone:
          $ref: '#/components/schemas/PhoneNumber'
        role:
          $ref: '#/components/schemas/Role'
          default: User
          description: The role assigned to the user.
        username:
          description: The username of the user.
          example: johndoe
          type: string
      required:
        - id
        - email
        - phone
        - role
        - is_active
        - created_at
      type: object

Note:

• If a property type is Option<T>, it is considered optional in the schema and it is not listed under required.
• Primitive types are automatically mapped to their OpenAPI equivalents (e.g., u32 to integer with format: int32).
• Custom types annotated with @openapi-type can be defined for more complex schema definitions.
• Enums are represented as string enums in the schema.
• Doc comments can include additional OpenAPI attributes like example, format, pattern, and description.
• The generator supports common Rust types and can be extended for more complex scenarios.

🏷️ Renaming & Implicit Export Safety (v0.1.2+)

Implicit Safety: Enums now require the @openapi tag to be exported to the schema. Enums without this tag are ignored, even if public.

Renaming: You can rename fields, variants, and structs using Serde attributes or @openapi directives. Precedence Order:

1. Manual @openapi rename / @openapi rename-all
2. #[serde(rename = "...")] / #[serde(rename_all = "...")]
3. Default Rust Name

Example: Renaming & Serde Support

/// @openapi
/// @openapi rename-all camelCase
#[derive(serde::Serialize)] // Optional, used for reference
pub enum UserRole {
    /// @openapi rename "admin_user"
    Admin,
    Moderator, // -> "moderator" (camelCase)
    User       // -> "user"
}

/// @openapi rename "UserProfile"
#[serde(rename_all = "snake_case")]
pub struct Profile {
    pub first_name: String, // -> "first_name"
    
    /// @openapi rename "lastName"
    pub last_name: String,  // -> "lastName" (override)
}

🏷️ Adjacently Tagged Enums

Supports #[serde(tag = "...")] (Internally Tagged) and #[serde(tag = "...", content = "...")] (Adjacently Tagged) to generate oneOf schemas with a discriminator.

/// @openapi
#[derive(Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum StorageConfig {
    /// Generates schema "StorageConfigLocal"
    Local { root_path: String },
    
    /// Generates schema "StorageConfigS3"
    S3 { bucket: String, region: String },
}

/// @openapi
#[derive(Serialize)]
#[serde(tag = "t", content = "c")]
pub enum MyResult {
    Ok(String),
    Err { code: i32 }
}

Generates:

• StorageConfig container with oneOf.
• StorageConfigLocal: { type: "local", root_path: "..." }
• MyResult: container.
• MyResultOk: { t: "Ok", c: { type: "string" } }
• MyResultErr: { t: "Err", c: { type: "object", properties: { code: ... } } }

✅ Validation Attributes

Supports the validator crate's #[validate(...)] attributes to automatically populate OpenAPI keywords.

#[derive(Validate)]
pub struct UserDto {
    #[validate(email)]
    pub email: String,              // -> format: email

    #[validate(url)]
    pub website: String,            // -> format: uri

    #[validate(length(min = 3, max = 20))]
    pub username: String,           // -> minLength: 3, maxLength: 20

    #[validate(range(min = 18, max = 100))]
    pub age: u8,                    // -> minimum: 18, maximum: 100
    
    #[validate(regex = "path")]     // -> pattern: "..." (if literal provided)
    pub code: String,
}

🧬 Template schemas with generics

Define reusable schema templates with generics using the $ prefix.

/// Paginated response wrapper.
/// @openapi<T>
pub struct PaginatedResponse<T> {
  /// @openapi example: 100
  pub total_count: u32,

  /// @openapi
  /// example: 1
  /// minimum: 1
  pub page: u32,

  /// @openapi
  /// example: 10
  /// minimum: 1
  /// maximum: 1000
  pub limit: u32,

  pub data: Vec<T>,
} 

Usage:

// More about this in the Route DSL section below.
/// @return 200: $PaginatedResponse<User> "Success"

generates:

components:
  schemas:
    PaginatedResponse_User:
      description: Paginated response wrapper.
      properties:
        data:
          items:
            $ref: '#/components/schemas/User'
          type: array
        limit:
          example: 10
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
        page:
          example: 1
          format: int32
          minimum: 1
          type: integer
        total_count:
          example: 100
          format: int32
          type: integer
      required:
      - total_count
      - page
      - limit
      - data
      type: object 

Note:

• The Monomorphizer pass generates concrete schemas for each unique instantiation of the generic template (e.g., $PaginatedResponse<User> becomes PaginatedResponse_User).
• Multiple generic parameters are supported (e.g., $Result<T, E> => Result_T_E).

🌳 Root Documentation

Every OpenAPI specification needs a root definition containing metadata like the API version, title, and global security schemes. oas-forge requires exactly one such root definition in your project. You can define this using a standard @openapi block, typically on a unit struct or at the top of your main.rs / lib.rs.

1. Basic Root Definition

The root definition must contain the openapi version and the info object.

/// @openapi
/// openapi: 3.1.0
/// info:
///   title: My Awesome API
///   version: 1.0.0
///   description: >
///     This is the main entry point for the API documentation.
///     You can use Markdown here.

2. Variable Substitution

oas-forge automatically injects environment variables into your documentation. The most common use case is syncing the API version with your crate version.

• {{CARGO_PKG_VERSION}}: Replaced by the version from Cargo.toml.

/// @openapi
/// openapi: 3.1.0
/// info:
///   title: Starr API
///   # Automatically uses the version from Cargo.toml
///   version: {{CARGO_PKG_VERSION}}

3. Defining Global Security Schemes

The root definition is the perfect place to define securitySchemes (Components) and global security requirements.

/// @openapi
/// openapi: 3.1.0
/// info:
///   title: Secure API
///   version: 1.0.0
/// components:
///   securitySchemes:
///     # Define a JWT Bearer scheme
///     BearerAuth:
///       type: http
///       scheme: bearer
///       bearerFormat: JWT
///     # Define an OAuth2/OIDC scheme
///     OidcAuth:
///       type: openIdConnect
///       openIdConnectUrl: [https://auth.example.com/.well-known/openid-configuration](https://auth.example.com/.well-known/openid-configuration)
/// # Apply BearerAuth globally to all routes (optional)
/// security:
///   - BearerAuth: []

4. Attaching to Application Logic (Recommended)

You don't need to create a "lifeless" dummy struct just for documentation. You can attach the root definition directly to your main application entry point or router function. This keeps the documentation close to the actual code logic.

/// @openapi
/// openapi: 3.1.1
/// info:
///   title: User Management API
///   version: {{CARGO_PKG_VERSION}}
///   description: API documentation for the user service.
/// components:
///   securitySchemes:
///     oidcAuth:
///       type: openIdConnect
///       openIdConnectUrl: $$OIDC_URL/.well-known/openid-configuration
///       description: OIDC Authentication via Rauthy.
pub fn create_app() -> Router<AppState> {
  Router::new()
    .nest("/docs", swagger::router())
    .nest("/users", users::router())
}

🧩 Fragments & Mixins

Fragments allow you to define reusable OpenAPI snippets (like common error responses, standard parameters, or security schemes) and inject them into your operation definitions.

1. Defining Fragments

Fragments are usually defined in a shared file (e.g., lib.rs or docs.rs) using module-level comments (//!). They can accept parameters using the {{variable}} syntax.

//! ---------------------------------------------------------------------------
//! A. Fragment for a List (e.g., Parameters)
//! ---------------------------------------------------------------------------
//! @openapi-fragment PaginationParams
//! - name: page
//!   in: query
//!   description: Page number
//!   schema: { type: integer, default: 1 }
//! - name: limit
//!   in: query
//!   schema: { type: integer, default: 10 }

//! ---------------------------------------------------------------------------
//! B. Fragment for an Object (e.g., Responses or Security)
//! ---------------------------------------------------------------------------
//! @openapi-fragment Secured(role)
//! security:
//!   - oidcAuth: [ {{role}} ]
//! responses:
//!   '401':
//!     description: Unauthorized
//!   '403':
//!     description: Forbidden - Requires {{role}} role

2. Usage: @insert vs. @extend

While both keywords inject content, they work at different levels. Choosing the right one is crucial for valid YAML generation.

Keyword	Mechanism	Best Used For	Behavior
@insert	Textual Substitution	Lists / Arrays	Acts like "Copy & Paste". Replaces the line with the fragment text before parsing. Essential for inserting items into a YAML list (like parameters).
@extend	Deep Merge	Objects / Maps	Parses the fragment as YAML and deeply merges it into the current structure. Ideal for adding fields to a struct or responses to an operation.

Example: Using @insert (For Lists)

Use @insert when you want to add elements to a list, such as query parameters.

/// @openapi
/// paths:
///   /users:
///     get:
///       parameters:
///         # Inserts the list items directly here
///         @insert PaginationParams

Example: Using @extend (For Objects)

Use @extend when you want to merge properties, such as adding security requirements or standard responses to an existing block.

/// @openapi
/// paths:
///   /admin/dashboard:
///     get:
///       summary: Admin Area
///       
///       # Merges security and 401/403 responses into this operation
///       @extend Secured("admin")
///
///       responses:
///         '200':
///           description: OK

📚 Reference: Default Type Mappings

oas-forge automatically recognizes common Rust types (including popular crates like chrono, uuid, and url) and maps them to their OpenAPI equivalents.

Rust Type	OpenAPI Type	Format	Notes
bool	boolean	-
String, &str, char	string	-
i8, i16, i32, u8, u16, u32	integer	int32
i64, u64, isize, usize	integer	int64	usize and isize are treated as 64-bit.
f32	number	float
f64	number	double
Uuid	string	uuid	e.g., from uuid crate
NaiveDate	string	date	e.g., from chrono crate
DateTime, NaiveDateTime	string	date-time	e.g., from chrono crate
NaiveTime	string	time	e.g., from chrono crate
Url, Uri	string	uri
Decimal, BigDecimal	string	decimal	String representation to preserve precision.
ObjectId	string	objectid	MongoDB/BSON identifier
serde_json::Value	-	-	Maps to {} (Any Type).

Axum/Swagger basic example without route dsl

use crate::app::AppState;
use axum::{
    Router,
    http::header,
    response::{Html, IntoResponse},
    routing::get,
};
use std::env;

const OPENAPI_SPEC: &str = include_str!("../../openapi.yaml");

const OIDC_PLACEHOLDER: &str = "$$OIDC_URL";
const DEFAULT_OIDC_URL: &str = "https://oidc.example.com";

pub fn router() -> Router<AppState> {
    Router::new()
        .route("/openapi.yaml", get(serve_spec))
        .route("/swagger", get(serve_ui))
}

/// @openapi
/// paths:
///   /docs/openapi.yaml:
///     get:
///       tags: [System]
///       summary: Get OpenAPI Specification
///       description: Returns the dynamic OpenAPI 3.1.1 specification with runtime configuration.
///       responses:
///         '200':
///           description: The OpenAPI YAML file.
///           content:
///             application/yaml:
///               schema:
///                 type: string
async fn serve_spec() -> impl IntoResponse {
    let oidc_url = env::var("OIDC_URL").unwrap_or_else(|_| DEFAULT_OIDC_URL.to_string());
    let dynamic_spec = OPENAPI_SPEC.replace(OIDC_PLACEHOLDER, &oidc_url);

    ([(header::CONTENT_TYPE, "application/yaml")], dynamic_spec)
}

/// @openapi
/// paths:
///   /docs/swagger:
///     get:
///       tags: [System]
///       summary: Swagger UI
///       description: Renders the Swagger UI.
///       responses:
///         '200':
///           description: HTML Page containing the Swagger UI.
///           content:
///             text/html:
///               schema:
///                 type: string
async fn serve_ui() -> impl IntoResponse {
    let html = r#"
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Starr API - Swagger UI</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
    <style>
        body { margin: 0; padding: 0; }
        #swagger-ui { max-width: 1400px; margin: 0 auto; }
    </style>
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
    <script>
        window.onload = () => {
            window.ui = SwaggerUIBundle({
                url: '/docs/openapi.yaml',
                dom_id: '#swagger-ui',
                deepLinking: true,
                presets: [
                    SwaggerUIBundle.presets.apis,
                    SwaggerUIBundle.SwaggerUIStandalonePreset
                ],
                layout: "BaseLayout",
            });
        };
    </script>
</body>
</html>
"#;
    Html(html)
}

📜 License

This project is licensed under the MIT license.