常见问题解答

问：能否从我的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(...)]语法。有关更多信息，请参阅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 也内置了相应的函数。

问：我能否将此与 Rocket 以外的其他 Web 框架一起使用？

答：是的，但目前没有其他实现。但您可以使用独立的 Okapi 包，并使用 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：启用 Rocket 的 msgpack 支持。（当使用相同的 Rocket 功能标志时。）
• secrets：启用 Rocket 的 secrets 支持。（当使用相同的功能标志时。）
• mtls：启用 Rocket 的 mutual TSL。（当使用相同的功能标志时。）
• 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 文件。然后，此文件/结构将存储在内存中，并在请求时提供服务。

The Rocket-Okapi-codegen 包包含 derive 宏 的代码。在我们的例子中包括 #[openapi]、rocket_okapi::openapi_spec![...]、rocket_okapi::openapi_routes![...] 和 #[derive(OpenApiFromRequest)]。由于 Rust 的限制，这需要在一个单独的包中。注意：与 derive 或 codegen 包相比，其他包通常更难操作。因此，建议在更改此处之前，先了解 derive 宏是如何工作的。

待办事项

• 测试
• 文档
• 基准测试/优化内存使用和分配
  • 备注： https://crates.io/crates/graphannis-malloc_size_of 看起来很有用
• 实现 OpenApiFrom___/OpenApiResponder 以支持更多的 rocket/rocket-contrib 类型
• 允许自定义 openapi 生成设置，例如
  • 自定义 JSON 模式生成设置
  • 更改文档所在路径

许可协议

本项目采用 MIT 许可协议。

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