常见问题解答

问：我可以从我的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 也内置了函数。

问题：我可以用它与其他 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 的 秘密支持。（当使用相同的功能标志时。）
• 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"示例。（确保包版本匹配）

工作原理

此包在Rocket服务器启动时自动生成一个OpenAPI文件。其工作原理简要描述如下。

Schemars包为我们提供了所有不同结构和枚举的架构。Okapi不会直接实现任何架构，这一切都由Schemars处理。

Okapi包仅包含创建OpenAPI文件所需的所有结构。此包不包含创建它们的任何代码，仅包含合并两个OpenAPI结构的结构和代码。此包可以重复使用以在其他Web框架中创建OpenAPI支持。

Rocket-Okapi包包含生成OpenAPI文件并一旦创建后提供服务的所有代码。此代码通常使用宏执行，例如：mount_endpoints_and_merged_docs!{...}、openapi_get_routes![...]、openapi_get_routes_spec![...]和openapi_get_spec![...]。

当Rocket服务器启动时（或宏放置的位置）将一次性生成OpenAPI文件。然后，该文件/结构将存储在内存中，并在请求时提供。

《Rocket-Otter-codegen》crate 包含了 派生宏 的代码。在我们的情况下，包括 #[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 看起来很有用
• 为更多的 rocket/rocket-contrib 类型实现 OpenApiFrom___/OpenApiResponder
• 允许自定义 openapi 生成设置，例如：
  • 自定义 JSON 架构生成设置
  • 更改文档所在的路径

许可证

本项目采用 MIT 许可证。

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