okapi-operation

这是一个库，允许使用过程宏 #[openapi] 生成 OpenAPI 的操作定义（使用来自 okapi 包的类型）。

示例（使用 axum-integration 功能）。

use axum::{extract::Query, Json};
use okapi_operation::{axum_integration::*, *};
use serde::Deserialize;

#[derive(Deserialize, JsonSchema)]
struct Request {
    /// Echo data
    data: String,
}

#[openapi(
    summary = "Echo using GET request",
    operation_id = "echo_get",
    tags = "echo",
    parameters(
        query(name = "echo-data", required = true, schema = "std::string::String",),
        header(name = "x-request-id", schema = "std::string::String",)
    )
)]
async fn echo_get(query: Query<Request>) -> Json<String> {
    Json(query.0.data)
}

#[openapi(
    summary = "Echo using POST request",
    operation_id = "echo_post",
    tags = "echo"
)]
async fn echo_post(
    #[body(description = "Echo data", required = true)] body: Json<Request>,
) -> Json<String> {
    Json(body.0.data)
}

fn main() {
    let app = Router::new()
        .route("/echo/get", get(openapi_handler!(echo_get)))
        .route("/echo/post", post(openapi_handler!(echo_post)))
        .finish_openapi("/openapi", "Demo", "1.0.0")
        .expect("no problem");
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app.into_make_service()).await.unwrap()
}

特性

• macro：启用 #[openapi] 宏的重导入（默认启用）；
• axum-integration：启用与 axum 包（https://github.com/tokio-rs/axum）的集成（实现某些 axum 类型的特性）
  • 与 axum 的兼容性：由于集成严重依赖于 axum 类型，此包只能与少量（可能甚至只有一个）最新的 axum 版本兼容；
  • 当前支持的 axum 版本：0.7.x。
• yaml：启用在存在 Accept 报头且值为 yaml 的情况下以 yaml 格式提供服务规范的能力。否则，在值 json|*/* 或空的情况下，将提供 json（目前仅影响 axum-integration）。

待办事项

• 支持在 MediaType 或 Parameter 上提供示例（通过 JsonSchema 宏支持类型示例）
• 支持从函数定义中推断参数的模式
• 支持在宏中重命名或更改路径到 okapi/schemars/okapi-operations
• 更多示例
• ...