rust-backend-api
为Rust后端提供API设计模式,包括使用validator进行请求验证,使用utoipa生成OpenAPI文档,以及SwaggerUI集成。在使用Axum构建REST API、添加请求验证、生成OpenAPI规范或设置API文档时使用。
📖 中文导读:为Rust后端提供API设计模式,包括使用validator进行请求验证,使用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