Swagger/OpenAPI 生成用于 Rust：Utoipa 库

Swagger/OpenAPI 生成用于 Rust：Utoipa — 现代自动文档工具

在 Rust 中开发 Web 应用程序时，API 文档不是奢侈品，而是必需品。Utoipa 库（"Utopia" 的缩写）提供了一种强大而优雅的方式，直接从代码生成 OpenAPI 规范。它与流行的 Web 框架集成，例如 actix-web、axum、rocket 和 warp，并允许使用属性和宏来描述端点、数据模式和参数。

Utoipa 的主要功能

• 自动生成 OpenAPI 3.0/3.1 — 无需手动编写 YAML/JSON。
• 支持多种框架 — actix-web、axum、rocket、warp。
• 与 Swagger UI 集成 — 内置组件用于可视化文档。
• 深入的模式描述 — 支持嵌套结构、枚举、可选字段。
• 用于快速描述的宏 — #[utoipa::path]、#[openapi]。
• 规范验证 — 检查生成文档的正确性。

安装与配置

在 Cargo.toml 中添加依赖项。例如，我们选择 actix-web 框架：

[dependencies]utoipa = "4"utoipa-swagger-ui = { version = "4", features = ["actix-web"] }actix-web = "4"serde = { version = "1", features = ["derive"] }

基本示例：创建带文档的 API

考虑一个针对“用户”实体的简单 CRUD。我们从定义数据模型开始：

use serde::{Deserialize, Serialize};use utoipa::ToSchema;

#[derive(Serialize, Deserialize, ToSchema)]pub struct User {    #[schema(example = "1")]    pub id: i32,    #[schema(example = "john_doe")]    pub username: String,    #[schema(example = "john@example.com")]    pub email: String,}

现在，我们使用宏 #[utoipa::path] 描述获取用户列表的端点：

use actix_web::{get, web, HttpResponse, Responder};use utoipa::OpenApi;

#[utoipa::path(    get,    path = "/users",    responses(        (status = 200, description = "用户列表", body = Vec<User>)    ))]#[get("/users")]async fn get_users() -> impl Responder {    let users = vec![        User { id: 1, username: "alice".into(), email: "alice@example.com".into() },        User { id: 2, username: "bob".into(), email: "bob@example.com".into() },    ];    HttpResponse::Ok().json(users)}

构建 OpenAPI 文档和 Swagger UI

创建一个结构体来描述整个 API：

#[derive(OpenApi)]#[openapi(    paths(get_users),    components(schemas(User)))]pub struct ApiDoc;

// 在 main 函数中配置 Swagger UIuse utoipa_swagger_ui::SwaggerUi;

#[actix_web::main]async fn main() -> std::io::Result<()> {    use actix_web::App;

    HttpServer::new(|| {        App::new()            .service(get_users)            .service(                SwaggerUi::new("/swagger-ui/{_:.*}")                    .url("/api-docs/openapi.json", ApiDoc::openapi())            )    })    .bind("127.0.0.1:8080")?    .run()    .await}

启动应用程序后，文档将在 http://localhost:8080/swagger-ui/ 地址可用。

高级功能：嵌套模式和参数

Utoipa 支持复杂数据类型。例如，添加一个包含嵌套结构的字段：

#[derive(Serialize, Deserialize, ToSchema)]pub struct Address {    #[schema(example = "莫斯科市")]    pub city: String,    #[schema(example = "列宁大街 1 号")]    pub street: String,}