9 个版本 (破坏性更新)
0.7.0 | 2024年1月14日 |
---|---|
0.7.0-rc.1 | 2021年10月10日 |
0.6.0-alpha-1 | 2021年6月12日 |
0.5.0-alpha-1 | 2020年6月12日 |
0.1.2 | 2019年10月12日 |
#1 在 #swagger
25,889 每月下载量
用于 20 个 crate(直接使用10个)
44KB
752 行
Okapi
为 Rust/Rocket 项目自动生成 OpenAPI(又称 Swagger)文档。
不再需要过时的文档。Okapi 在设置服务器时会为您生成文档。它使用 Rust Doc 注释和编程逻辑的组合来记录您的 API。
生成的 OpenAPI 文件可以被各种程序用来可视化文档。Rocket-okapi 目前包括 RapiDoc 和 Swagger UI,但也支持其他工具。
支持的 OpenAPI 规范:3.0.0
支持的 Rocket 版本(对于 rocket_okapi
):0.5.0
使用 Okapi 生成的文档示例
- DF Storyteller: RapiDoc,Swagger UI
- ...[^1]
[^1]: 将添加更多示例,如果您有好的示例,请提交问题。
示例
- Json 网络API:显示 Okapi 基本功能的简单示例。
- UUID:简单的示例,展示基础用法,但使用UUID而不是普通的
u32
/u64
标识。 - 自定义模式:展示如何向OpenAPI文件添加更多/自定义信息,并将多个模块合并为一个OpenAPI文件。
- 安全请求守护者:展示如何在OpenAPI文件中实现身份验证方法。包括:无身份验证、API密钥、HTTP身份验证、OAuth2、OpenID和Cookies。
- 特殊类型:展示一些更不常见的类型及其用法。(仍在开发中)
- 还有更多
常见问题解答(FAQ)
问题:我能从我的OpenAPI文件生成代码吗?
回答:不,这个crate只允许您从您的代码自动生成OpenAPI文件。还有其他crate可以(尝试)做到这一点。所以
- (Rust代码(Rocket)--> OpenAPI) == Okapi
- (OpenAPI --> Rust代码) != Okapi
问题:我该如何记录我的端点?
回答:Okapi自动使用来自大多数地方的Rust文档注释,这包括:- 端点函数。- 端点函数参数,使用Schemars。除非在另一个struct
中使用,否则无法为String
和其他默认类型添加文档。有关更多信息,请参阅此问题。- 端点函数返回类型,使用Schemars。应用相同的规则。在Result<T, E>
的情况下,可以记录错误代码,请参阅此示例。
可以使用#[openapi(...)]
derive宏提供更多信息,有关更多信息,请参阅OpenApiAttribute。
Schemars还可以用于为实现#[derive(JsonSchema)]
的对象提供更多信息,使用#[schemars(...)]
和#[serde(...)]
语法。有关更多信息,请参阅代码。
文档的许多其他地方也可以增强,但可能需要自定义实现。 查看我们的示例以获取更多信息。
如果上述方法不足以满足需求,您始终可以创建自己的自定义 OpenAPI
对象。然后可以将这些对象合并到最终的 OpenAPI 文件中。 更多信息请参阅此示例。只有当真的有必要时才使用此方法!(因为它可能会覆盖其他生成的对象。)
问题:我的(diesel)数据库没有实现 OpenApiFromRequest
。
答案:这是因为参数没有出现在路径、查询或正文中。因此,这被视为 请求保护。有一个为此的 派生宏,但这个宏与 #[database)"..."]
宏不兼容。您可以手动实现它,如下所示
为 Diesel DB 实现 `OpenApiFromRequest`
use rocket_okapi::request::{OpenApiFromRequest, RequestHeaderInput};
use rocket_okapi::gen::OpenApiGenerator;
use rocket_sync_db_pools::{diesel, database};
#[database("sqlite_logs")]
pub struct MyDB(diesel::SqliteConnection);
impl<'r> OpenApiFromRequest<'r> for MyDB {
fn from_request_input(
_gen: &mut OpenApiGenerator,
_name: String,
_required: bool,
) -> rocket_okapi::Result<RequestHeaderInput> {
Ok(RequestHeaderInput::None)
}
}
问题:... 是否没有实现 JsonSchema
?
答案:JsonSchema
实现由 Schemars
处理,请确保已为它启用了正确的 功能标志。如果它仍未实现,请在 Schemars
存储库中打开一个问题。
问题:我可以在我的 OpenAPI 规范中添加自定义数据吗?
答案:是的,请参阅 自定义模式 示例。如果您想手动合并 OpenAPI
对象,Okapi 还具有内置函数。
问题:我可以使用此方法与 Rocket 以外的其他 Web 框架吗?
答案:可以,但目前还没有其他实现。但是,您可以独立使用 Okapi
crate 并使用 Serde 创建 json 或 yaml 文件。
功能标志
Okapi
impl_json_schema
:为Schemars
和Okapi
类型本身实现JsonSchema
。preserve_order
:在Schema
和OpenAPI
文档的所有部分中保留结构体字段的顺序。
Rocket-Okapi
preserve_order
:在Schema
和OpenAPI
文档的所有部分中保留结构体字段的顺序。swagger
:启用 Swagger UI 以呈现文档。rapidoc
:启用 RapiDoc 以呈现文档。uuid
:启用 Rocket 和 Schemars 中的 UUID 支持。msgpack
:启用 msgpack 支持(当使用相同的 Rocket 功能标志时)。secrets
:启用 秘密支持(当使用相同的功能标志时)。mtls
:启用 相互 TLS(当使用相同的功能标志时)。rocket_dyn_templates
:启用与rocket_dyn_templates
的兼容性。rocket_db_pools
:启用与rocket_db_pools
的兼容性。rocket_sync_db_pools
:启用与rocket_sync_db_pools
的兼容性。rocket_ws
:启用与rocket_ws
的兼容性。
注意,并非所有来自 Schemars
的功能标志都重新导出或启用。因此,如果您有未实现 JsonSchema
特性的对象,您可能需要在 Schemars
中启用一个 功能标志。例如,请参阅 "uuid1" 示例。(确保crate版本匹配)
工作原理
当Rocket服务器启动时,此crate会自动生成一个OpenAPI文件。这里简要描述了这是如何完成的。
Schemars
crate为我们提供了所有不同结构和枚举的架构。Okapi没有直接实现任何架构,这全部由 Schemars
处理。
Okapi
crate只包含创建OpenAPI文件所需的所有结构。此crate不包含创建它们的代码,只是合并两个 OpenAPI
结构的代码和结构。此crate可以重用来创建其他Web框架中的OpenAPI支持。
Rocket-Okapi
crate包含生成OpenAPI文件并在创建后提供服务的所有代码。此代码通常使用宏执行,例如: mount_endpoints_and_merged_docs!{...}
,openapi_get_routes![...]
,openapi_get_routes_spec![...]
和 openapi_get_spec![...]
。
当Rocket服务器启动(或宏放置的位置)时,OpenAPI文件将生成一次。然后此文件/结构将存储在内存中,并在请求时提供服务。
Rocket-Okapi-codegen
crate包含用于 derive宏 的代码。在我们的例子中,是 #[openapi]
,rocket_okapi::openapi_spec![...]
,rocket_okapi::openapi_routes![...]
和 #[derive(OpenApiFromRequest)]
。这需要在一个单独的crate中,因为Rust的限制。注意:与其它crate相比,derive
或 codegen
crate通常难以工作。因此,在更改此处之前,建议您先获得一些关于derive宏如何工作的经验。
待办事项
- 测试
- 文档
- 基准/优化内存使用和分配
- 实现
OpenApiFrom___
/OpenApiResponder
以支持更多 rocket/rocket-contrib 类型 - 允许自定义 OpenAPI 生成设置,例如:
- 自定义 JSON schema 生成设置
- 更改文档托管路径
许可证
本项目采用 MIT 许可证。
对本项目的所有贡献都将采用类似的许可证。
依赖项
~0.8–1.7MB
~38K SLoC