9 个版本 (破坏性更新)

0.7.0 2024年1月14日
0.7.0-rc.12021年10月10日
0.6.0-alpha-12021年6月12日
0.5.0-alpha-12020年6月12日
0.1.2 2019年10月12日

#1#swagger

Download history 6326/week @ 2024-03-14 6276/week @ 2024-03-21 6046/week @ 2024-03-28 6014/week @ 2024-04-04 6404/week @ 2024-04-11 7903/week @ 2024-04-18 6830/week @ 2024-04-25 6044/week @ 2024-05-02 5975/week @ 2024-05-09 7199/week @ 2024-05-16 6122/week @ 2024-05-23 5260/week @ 2024-05-30 5557/week @ 2024-06-06 6784/week @ 2024-06-13 6556/week @ 2024-06-20 6013/week @ 2024-06-27

25,889 每月下载量
用于 20 个 crate(直接使用10个)

MIT 许可证

44KB
752

Okapi

Okapi: 下载 API 文档

Rocket-Okapi: 下载 API 文档

unsafe forbidden

为 Rust/Rocket 项目自动生成 OpenAPI(又称 Swagger)文档。

不再需要过时的文档。Okapi 在设置服务器时会为您生成文档。它使用 Rust Doc 注释和编程逻辑的组合来记录您的 API。

生成的 OpenAPI 文件可以被各种程序用来可视化文档。Rocket-okapi 目前包括 RapiDocSwagger UI,但也支持其他工具。

支持的 OpenAPI 规范:3.0.0
支持的 Rocket 版本(对于 rocket_okapi):0.5.0

使用 Okapi 生成的文档示例

[^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:为 SchemarsOkapi 类型本身实现 JsonSchema
  • preserve_order:在 SchemaOpenAPI 文档的所有部分中保留结构体字段的顺序。

Rocket-Okapi

  • preserve_order:在 SchemaOpenAPI 文档的所有部分中保留结构体字段的顺序。
  • 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相比,derivecodegen crate通常难以工作。因此,在更改此处之前,建议您先获得一些关于derive宏如何工作的经验。

待办事项

  • 测试
  • 文档
  • 基准/优化内存使用和分配
  • 实现 OpenApiFrom___/OpenApiResponder 以支持更多 rocket/rocket-contrib 类型
  • 允许自定义 OpenAPI 生成设置,例如:
    • 自定义 JSON schema 生成设置
    • 更改文档托管路径

许可证

本项目采用 MIT 许可证

对本项目的所有贡献都将采用类似的许可证。

依赖项

~0.8–1.7MB
~38K SLoC