常见问题解答

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

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

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

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

答：Okapi自动使用来自大多数地方的Rust文档注释，这包括：- 端点函数。 - 端点函数参数，使用Schemars。除非在另一个struct中使用，否则无法为String和其他默认类型添加文档。有关更多信息，请参阅此问题。- 端点函数返回类型，使用Schemars。规则与参数相同。在Result<T, E>的情况下，可以记录错误代码，请参阅此示例。

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

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

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

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

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

A: 这是因为参数没有出现在路径、查询或体中。因此，这被视为一个请求保护。有一个衍生宏可以用于此，但它不能与#[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)
    }
}

Q: ... 是否实现了 JsonSchema？

A: JsonSchema 的实现由 Schemars 处理，请确保您已启用了正确的 功能标志。如果仍未实现，请在 Schemars 仓库中打开一个问题。

Q: 我能否向我的 OpenAPI 规范添加自定义数据？

A: 是的，请参阅 自定义模式示例。如果您想手动合并 OpenAPI 对象，Okapi 也内置了函数。

Q: 我能否使用 Rocket 以外的其他 Web 框架？

A: 是的，但目前还没有其他实现。但您可以使用独立的 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: 启用 Rocket 中的 msgpack 支持。（当使用相同的 Rocket 功能标志时。）
• secrets: 启用 Rocket 中的 密钥支持。（当使用相同的功能标志时。）
• mtls: 启用 Rocket 中的 双向 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)]。由于Rust的限制，这需要在单独的crate中。注意：与其他crate相比，derive 或 codegen crate通常更难处理。因此，在更改此处之前，建议您先获得一些关于derive宏的工作方式的经验。

待办事项

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

许可证

本项目采用 MIT 许可证。

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