Okapi

Okapi:

Rocket-Okapi:

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

永远不会有过时的文档。Okapi 在设置服务器的同时为您生成文档。它结合了 Rust 文档注释 和编程逻辑来记录您的 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]: 将添加更多示例，如果您有好的示例，请提交 issue。

示例

• JSON 网络API：显示 Okapi 基本功能的简单示例。
• UUID：显示基本功能，但使用 UUID 而不是正常的 u32/u64 ID。
• 自定义模式：展示如何向OpenAPI文件添加更多/自定义信息，并将多个模块合并成一个OpenAPI文件。
• 安全请求守护者：展示如何在OpenAPI文件中实现认证方法。包括：无认证、API密钥、HTTP认证、OAuth2、OpenID和Cookies。
• 特殊类型：展示一些不太常见的类型及其使用方法。（仍在进行中）
• 还有更多

常见问题解答

问：我可以从我的OpenAPI文件生成代码吗？

答：不可以，这个crate只允许您从代码自动生成OpenAPI文件。还有其他crate（尝试）这样做。所以

• (Rust代码（Rocket）--> OpenAPI) == Okapi
• (OpenAPI --> Rust代码) != Okapi

问：我该如何记录我的端点？

答：Okapi会自动使用大多数地方的Rust文档注释，这包括：- 端点函数。- 端点函数参数，使用Schemars。为String和其他默认类型添加文档是不可能的，除非它们被用在另一个struct中。更多信息请参阅这个问题。- 端点函数返回类型，使用Schemars。同样适用于参数。在Result<T, E>的情况下，错误代码可以被记录，请参阅这个示例。

可以使用#[openapi(...)] derive宏提供更多信息，更多信息请参阅：OpenApiAttribute。

Schemars也可以用于为实现了#[derive(JsonSchema)]的对象提供更多信息，使用#[schemars(...)]和#[serde(...)]语法。更多信息请参阅Attrs

文档可以在其他大多数地方进行增强，但可能需要自定义实现。请参阅我们的示例获取更多信息。

如果以上方法不足以满足您的需求，您总是可以创建自己的 OpenAPI 对象。然后可以将这些对象合并到最终的 OpenAPI 文件中。更多示例信息请参见此示例。只有在真正必要时才使用此方法！（因为它可能会覆盖其他生成的对象。）

问：我的（diesel）数据库没有实现 OpenApiFromRequest。

答：这是因为参数没有出现在路径、查询或正文中。因此，这被认为是 请求守卫。为此有一个 派生宏，但它不能与 #[database("...")] 宏一起使用。您可以手动实现它，如下所示

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 也内置了函数。

问：我可以用这个与其他 Web 框架一起使用吗？

答：是的，但目前还没有其他实现。但您可以使用 Okapi crate 独立使用，并用 Serde 创建 json 或 yaml 文件。

功能标志

Okapi

• impl_json_schema：为 JsonSchema 实现 Schemars 和 Okapi 类型本身。
• preserve_order：在 Schema 和所有 OpenAPI 文档的部分中保留结构字段顺序。

Rocket-Okapi

• preserve_order：在 Schema 和所有 OpenAPI 文档的部分中保留结构字段顺序。
• swagger：启用 Swagger UI 以渲染文档。
• rapidoc：启用 RapiDoc 以渲染文档。
• uuid：在 Rocket 和 Schemars 中启用 UUID 支持。
• msgpack：启用 msgpack 支持 对于 Rocket（当使用相同的 Rocket 功能标志时）。
• secrets：启用 秘密支持 对于 Rocket（当使用相同的功能标志时）。
• mtls：启用 相互 TLS 对于 Rocket（当使用相同的功能标志时）。
• 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![...]）来执行此代码。。