2个不稳定版本
| 0.3.0 | 2023年6月5日 |
|---|---|
| 0.2.0 | 2023年6月4日 |
| 0.1.0 |
|
在 过程宏 中排名 #496
14KB
206 行
utoipa_auto_discovery
Rust宏，用于自动化将路径/模式添加到Utoipa包，在编译阶段模拟反射
包介绍
Utoipa是一个通过源代码生成文档（openapi/swagger）的优秀包。
但鉴于Rust是静态编程语言，我们在运行时无法自动发现路径和dto，并将它们添加到文档中，
对于只有几个端点的API，逐个添加控制器函数和DTO并不麻烦。
如果你有数百甚至数千个端点，代码就会变得非常冗长且难以维护。
示例
...
#[derive(OpenApi)]
#[openapi(
paths(
// <================================ all functions 1 to N
test_controller::service::func_get_1,
test_controller::service::func_get_2,
test_controller::service::func_get_3,
test_controller::service::func_get_4,
....
....
....
test_controller::service::func_get_N,
),
components(
// <====================== All DTO one by one
schemas(TestDTO_1, TestDTO_2, ........ , TestDTO_N)
),
tags(
(name = "todo", description = "Todo management endpoints.")
),
modifiers(&SecurityAddon)
)]
pub struct ApiDoc;
...
包 utoipa_auto_discovery 的目的是提出一个宏，用于自动检测携带Utoipa宏的方法（#[utoipa::path(...]），并自动将其添加。 （它也检测子模块。）
如何使用它
简单地将crate utoipa_auto_discovery 添加到项目中
cargo add utoipa_auto_discovery
导入宏
use utoipa_auto_discovery::utoipa_auto_discovery;
然后在 #[derive(OpenApi)] 和 #[openapi] 宏之前添加 #[utoipa_auto_discovery] 宏。
重要！！
将 #[utoipa_auto_discovery] 放在 #[derive(OpenApi)] 和 #[openapi] 宏之前。
#[utoipa_auto_discovery(paths = "( MODULE_TREE::MODULE_NAME => MODULE_SRC_FILE_PATH ) ; ( MODULE_TREE::MODULE_NAME => MODULE_SRC_FILE_PATH ) ; ... ;")]
路径接收一个必须遵守此结构的String
"( 模块树路径 => 模块源文件路径 ) ;"
您可以通过分号 ";" 分隔来添加多个对（模块路径 => 源路径）。
以下是如何添加test_controller和test2_controller模块中所有方法的示例。您还可以结合自动和手动添加，就像这里我们手动将方法添加到文档中 "other_controller::get_users"。
...
use utoipa_auto_discovery::utoipa_auto_discovery;
...
#[utoipa_auto_discovery(
paths = "( crate::rest::test_controller => ./src/rest/test_controller.rs ) ; ( crate::rest::test2_controller => ./src/rest/test2_controller.rs )"
)]
#[derive(OpenApi)]
#[openapi(
paths(
crate::rest::other_controller::get_users,
),
components(
schemas(TestDTO)
),
tags(
(name = "todo", description = "Todo management endpoints.")
),
modifiers(&SecurityAddon)
)]
pub struct ApiDoc;
...
排除自动扫描的方法
您可以通过添加以下宏来从Doc Path列表中排除一个函数：#[utoipa_ignore]。
例
/// Get all pets from database
///
#[utoipa_ignore] //<============== this Macro
#[utoipa::path(
responses(
(status = 200, description = "List all Pets", body = [ListPetsDTO])
)
)]
#[get("/pets")]
async fn get_all_pets(req: HttpRequest, store: web::Data<AppState>) -> impl Responder {
// your CODE
}
注意
包含标记了utoipa::path标签的方法的子模块也会自动检测。
功能
- 自动路径检测
- 自动模式检测（进行中）
依赖关系
~265–710KB
~17K SLoC