openapi

OpenAPI Documentation Guidelines

This document provides comprehensive guidelines for writing OpenAPI annotations in the Sayna Rust/Axum codebase using the utoipa crate.

Overview

Sayna uses utoipa (v5.3+, latest is v5.4) for OpenAPI 3.1 specification generation. All OpenAPI-related code is feature-gated behind the openapi feature flag to keep dependencies minimal in production builds.

Key Principles

1. Feature-Gated: All OpenAPI code must be conditionally compiled with #[cfg_attr(feature = "openapi", ...)]
2. Centralized Documentation: All paths, schemas, and tags are registered in src/docs/openapi.rs
3. Complete Examples: Every field should have meaningful examples that reflect real-world usage
4. Consistent Style: Follow established patterns for naming, descriptions, and error responses
5. Type Safety: Leverage Rust's type system to ensure documentation matches implementation

Feature Flag Setup

Cargo.toml Configuration

[features]
openapi = [
    "dep:utoipa",
]

[dependencies]
utoipa = { version = "5.3", optional = true, features = ["axum_extras"] }

# Optional: For more ergonomic route registration
# utoipa-axum = { version = "0.2", optional = true }

Optional: Enhanced Axum Integration

Consider adding utoipa-axum for more ergonomic route registration:

use utoipa_axum::{routes, router::OpenApiRouter};

let (router, api) = OpenApiRouter::new()
    .routes(routes!(health_check, list_voices, speak_handler))
    .split_for_parts();

Running with OpenAPI

# Run server with OpenAPI endpoints
cargo run --features openapi

# Generate OpenAPI spec to file
cargo run --features openapi -- openapi -o docs/openapi.yaml

# Generate JSON format
cargo run --features openapi -- openapi --format json -o docs/openapi.json

Schema Annotations

Basic Schema Definition

Use #[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))] on all types exposed in the API:

use serde::{Deserialize, Serialize};

/// Health check response
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
pub struct HealthResponse {
    /// Server status
    #[cfg_attr(feature = "openapi", schema(example = "OK"))]
    pub status: String,
}