axum_doc

✨ Features

v0.2.0 Highlights

Core Features

📦 Installation

cargo install axum_doc

🚀 Usage

axum_doc \
 --base-dir . \
 --handler-file src/main.rs \
 --model-files src/form.rs,src/response.rs,src/types.rs \
 --output openapi.json

Parameters

📖 Example

use axum::{Json, routing::post, Router};
use serde::{Deserialize, Serialize};
/// User login credentials
#[derive(Deserialize)]
pub struct LoginForm {
 pub username: String,
 pub password: String,
}
/// User login response with token
#[derive(Serialize)]
pub struct LoginResponse {
 pub token: String,
 pub user_id: uuid::Uuid,
 pub username: String,
}
/// User login endpoint
///
/// Authenticates a user and returns a JWT token.
async fn login(Json(form): Json<LoginForm>) -> Json<LoginResponse> {
 Json(LoginResponse {
 token: "jwt_token".to_string(),
 user_id: uuid::Uuid::new_v4(),
 username: form.username,
 })
}
fn app() -> Router {
 Router::new().route("/login", post(login))
}

{
 "openapi": "3.0.0",
 "info": {
 "title": "Generated API",
 "version": "1.0.0"
 },
 "paths": {
 "/login": {
 "post": {
 "summary": "User login endpoint",
 "description": "Authenticates a user and returns a JWT token.",
 "operationId": "login",
 "requestBody": {
 "content": {
 "application/json": {
 "schema": { "$ref": "#/components/schemas/LoginForm" }
 }
 }
 },
 "responses": {
 "200": {
 "description": "Successful response",
 "content": {
 "application/json": {
 "schema": { "$ref": "#/components/schemas/LoginResponse" }
 }
 }
 }
 }
 }
 }
 },
 "components": {
 "schemas": {
 "LoginResponse": {
 "type": "object",
 "properties": {
 "token": { "type": "string" },
 "user_id": {
 "type": "string",
 "format": "uuid"
 },
 "username": { "type": "string" }
 }
 }
 }
 }
}

🔧 Supported Types

Primitive Types

Special Types

Generic Types

🏗️ Router Organization

Nested Routes

Router::new()
 .nest("/api/v1", user::router()) // Path prefix automatically applied

// In modules/mod.rs:
Router::new().nest("/api/v1/user", user::router())
// In modules/user/mod.rs (WRONG - causes /api/v1/user/api/v1/user/login):
Router::new().nest("/api/v1/user", handler::router())
// Correct approach - just return the handler router:
pub fn router() -> Router {
 handler::router() // No double-nesting
}

Merged Routes

Router::new()
 .route("/", get(root))
 .merge(auth::router()) // Cross-module composition

📝 Documentation Comments

/// Get user by ID
///
/// Retrieves user information by their unique identifier.
/// Returns 404 if the user doesn't exist.
async fn get_user(Path(id): Path<Uuid>) -> Json<User> {
 // ...
}

⚠️ Current Limitations

🔄 Changelog

v0.2.1 (Latest)

v0.2.0

v0.1.1

🧪 Testing

# Run all tests
cargo test
# Run only unit tests
cargo test --bin axum_doc
# Run only integration tests
cargo test --test integration_test

📄 License

axum_doc

✨ 功能特性

v0.2.0 亮点

核心功能

📦 安装

cargo install axum_doc

🚀 使用方法

axum_doc \
 --base-dir . \
 --handler-file src/main.rs \
 --model-files src/form.rs,src/response.rs,src/types.rs \
 --output openapi.json

参数说明

📖 使用示例

use axum::{Json, routing::post, Router};
use serde::{Deserialize, Serialize};
/// 用户登录凭据
#[derive(Deserialize)]
pub struct LoginForm {
 pub username: String,
 pub password: String,
}
/// 用户登录响应
#[derive(Serialize)]
pub struct LoginResponse {
 pub token: String,
 pub user_id: uuid::Uuid,
 pub username: String,
}
/// 用户登录端点
///
/// 验证用户身份并返回 JWT token。
async fn login(Json(form): Json<LoginForm>) -> Json<LoginResponse> {
 Json(LoginResponse {
 token: "jwt_token".to_string(),
 user_id: uuid::Uuid::new_v4(),
 username: form.username,
 })
}
fn app() -> Router {
 Router::new().route("/login", post(login))
}

{
 "openapi": "3.0.0",
 "info": {
 "title": "Generated API",
 "version": "1.0.0"
 },
 "paths": {
 "/login": {
 "post": {
 "summary": "用户登录端点",
 "description": "验证用户身份并返回 JWT token。",
 "operationId": "login",
 "requestBody": {
 "content": {
 "application/json": {
 "schema": { "$ref": "#/components/schemas/LoginForm" }
 }
 }
 },
 "responses": {
 "200": {
 "description": "Successful response",
 "content": {
 "application/json": {
 "schema": { "$ref": "#/components/schemas/LoginResponse" }
 }
 }
 }
 }
 }
 }
 },
 "components": {
 "schemas": {
 "LoginResponse": {
 "type": "object",
 "properties": {
 "token": { "type": "string" },
 "user_id": {
 "type": "string",
 "format": "uuid"
 },
 "username": { "type": "string" }
 }
 }
 }
 }
}

🔧 支持的类型

基本类型

特殊类型

泛型类型

🏗️ 路由组织

嵌套路由

Router::new()
 .nest("/api/v1", user::router()) // 路径前缀自动应用

// 在 modules/mod.rs 中:
Router::new().nest("/api/v1/user", user::router())
// 在 modules/user/mod.rs 中(错误 - 会导致 /api/v1/user/api/v1/user/login):
Router::new().nest("/api/v1/user", handler::router())
// 正确的方法 - 直接返回 handler 的 router:
pub fn router() -> Router {
 handler::router() // 避免双重嵌套
}

合并路由

Router::new()
 .route("/", get(root))
 .merge(auth::router()) // 跨模块组合

📝 文档注释

/// 根据 ID 获取用户
///
/// 通过唯一标识符检索用户信息。
/// 如果用户不存在,返回 404。
async fn get_user(Path(id): Path<Uuid>) -> Json<User> {
 // ...
}

⚠️ 当前限制

🔄 更新日志

v0.2.1 (最新版本)

v0.2.0

v0.1.1

🧪 测试

# 运行所有测试
cargo test
# 仅运行单元测试
cargo test --bin axum_doc
# 仅运行集成测试
cargo test --test integration_test

📄 许可证