rust-backend-api

majiayu000 的头像作者 majiayu000

为 Rust 后端提供 API 设计模式,包括使用验证器进行请求验证、使用 utoipa 进行 OpenAPI 文档以及 SwaggerUI 集成。在使用 Axum 构建 REST API、添加请求验证、生成 OpenAPI 规范或设置 API 文档时使用。

📖 中文导读:为 Rust 后端提供 API 设计模式,包括使用验证器进行请求验证、使用 utoipa 进行 OpenAPI 文档以及 SwaggerUI 集成。在使用 Axum 构建 REST API、添加请求验证、生成 OpenAPI 规范或设置 API 文档时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: rust-backend-api description: Provides API design patterns for Rust backends including request validation with validator, OpenAPI documentation with utoipa, and SwaggerUI integration. Use when building REST APIs with Axum, adding request validation, generating OpenAPI specs, or setting up API documentation.

Enable production-quality REST API development with type-safe request validation, automatic OpenAPI documentation, and interactive API exploration. 1. **Validation at the Edge** - Validate all external input immediately. 2. **Code-First OpenAPI** - Documentation lives in the code via derive macros. 3. **Schema as Contract** - ToSchema-derived types define the API contract. **Request Validation**
use validator::Validate;

#[derive(Debug, Deserialize, Validate, ToSchema)]
pub struct CreateUserRequest {
    #[validate(email)]
    #[schema(example = "user@example.com")]
    pub email: String,

    #[validate(length(min = 8, max = 64))]
    pub password: String,

    #[validate(length(min = 1, max = 100))]
    #[schema(example = "Jane Doe")]
    pub name: String,
}

pub async fn create_user(
    State(state): State<AppState>,
    Json(req): Json<CreateUserRequest>,
) -> Result<Json<UserResponse>, AppError> {
    req.validate()?;
    // ...
}
**OpenAPI with utoipa**
#[utoipa::path(
    post,
    path = "/users",
    tag = "users",
    request_body = CreateUserRequest,
    responses(
        (status = 201, description = "User created", body = UserResponse),
        (status = 400, description = "Validation error")
    )
)]
pub async fn create_user(/* ... */) { }

#[derive(OpenApi)]
#[openapi(
    info(title = "My API", version = "1.0.0"),
    tags((name = "users", description = "User management"))
)]
struct ApiDoc;

pub fn create_router(state: AppState) -> Router {
    let (router, api) = OpenApiRouter::with_openapi(ApiDoc::openapi())
        .routes(routes!(create_user))
        .split_for_parts();

    router
        .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", api))
        .with_state(state)
}
- [ ] All request types derive Validate with constraints - [ ] Validation errors return 400 with field-specific messages - [ ] All endpoints have #[utoipa::path] documentation - [ ] SwaggerUI accessible and shows all endpoints - [ ] OpenAPI spec includes security schemes if using auth