okapi-operation

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

示例（带有 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：在存在具有 yaml 值的 Accept 标头的条件下，启用在 yaml 格式下提供规范的能力。否则，在存在值 json|*/* 或为空的情况下，提供 json（目前仅影响 axum-integration）。

待办事项

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