Attribute Macro rovo 

#[rovo]

Macro that generates OpenAPI documentation from doc comments.

This macro automatically generates OpenAPI documentation for your handlers using doc comments with special annotations.

Documentation Format

Use Rust-style doc comment sections and metadata annotations:

Sections

• # Path Parameters - Document path parameters for primitive types
• # Responses - Document response status codes
• # Examples - Provide example responses
• # Metadata - Add tags, security, and other metadata

Path Parameters

For primitive path parameters (String, u64, Uuid, bool, etc.), you can document them directly without creating wrapper structs:

/// # Path Parameters
///
/// user_id: The user's unique identifier
/// index: Zero-based item index

The parameter names are inferred from the variable bindings in your function signature (e.g., Path(user_id) creates a parameter named user_id).

For complex types, continue using structs with #[derive(JsonSchema)].

Metadata Annotations

• @tag <tag_name> - Add a tag for grouping operations (can be used multiple times)
• @security <scheme_name> - Add security requirements (can be used multiple times)
• @id <operation_id> - Set a custom operation ID (defaults to function name)
• @hidden - Hide this operation from documentation
• @rovo-ignore - Stop processing annotations after this point

Additionally, the Rust #[deprecated] attribute is automatically detected and will mark the operation as deprecated in the OpenAPI spec.

Examples

Primitive Path Parameter

/// Get user by ID.
///
/// # Path Parameters
///
/// id: The user's numeric identifier
///
/// # Responses
///
/// 200: Json<User> - User found
/// 404: () - User not found
#[rovo]
async fn get_user(Path(id): Path<u64>) -> impl IntoApiResponse {
    // ...
}

Tuple Path Parameters

/// Get item in collection.
///
/// # Path Parameters
///
/// collection_id: The collection UUID
/// index: Item index within collection
///
/// # Responses
///
/// 200: Json<Item> - Item found
#[rovo]
async fn get_item(
    Path((collection_id, index)): Path<(Uuid, u32)>
) -> impl IntoApiResponse {
    // ...
}

Struct-based Path (for complex types)

/// Get a single Todo item.
///
/// Retrieve a Todo item by its ID from the database.
///
/// # Responses
///
/// 200: Json<TodoItem> - Successfully retrieved the todo item
/// 404: () - Todo item was not found
///
/// # Examples
///
/// 200: TodoItem::default()
///
/// # Metadata
///
/// @tag todos
#[rovo]
async fn get_todo(
    State(app): State<AppState>,
    Path(todo): Path<SelectTodo>  // SelectTodo implements JsonSchema
) -> impl IntoApiResponse {
    // ...
}

Deprecated Endpoint

/// This is a deprecated endpoint.
///
/// # Metadata
///
/// @tag admin
/// @security bearer_auth
#[deprecated]
#[rovo]
async fn old_handler() -> impl IntoApiResponse {
    // ...
}