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-rc.1

使用 Okapi 生成的文档示例

• DF Storyteller: RapiDoc, Swagger UI
• ...[^1]

[^1]: 将添加更多示例，如果您有好的示例，请提出问题。

基本用法

use rocket::{get, post, serde::json::Json};
use revolt_rocket_okapi::{openapi, openapi_get_routes, swagger_ui::*};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

// Derive JsonSchema for and request/response models
#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
struct User {
    user_id: u64,
    username: String,
    #[serde(default)]
    email: Option<String>,
}

// Add #[openapi] attribute to your routes
#[openapi]
#[get("/user/<id>")]
fn get_user(id: u64) -> Option<Json<User>> {
    Some(Json(User {
        user_id: id,
        username: "bob".to_owned(),
        email: None,
    }))
}

// You can tag your routes to group them together
#[openapi(tag = "Users")]
#[post("/user", data = "<user>")]
fn create_user(user: Json<User>) -> Json<User> {
    user
}

// You can skip routes that you don't want to include in the openapi doc
#[openapi(skip)]
#[get("/hidden")]
fn hidden() -> Json<&'static str> {
    Json("Hidden from swagger!")
}

pub fn make_rocket() -> rocket::Rocket {
    rocket::build()
        // openapi_get_routes![...] will host the openapi document at `openapi.json`
        .mount(
            "/",
            openapi_get_routes![get_user, create_user, hidden],
        )
        // You can optionally host swagger-ui too
        .mount(
            "/swagger-ui/",
            make_swagger_ui(&SwaggerUIConfig {
                url: "../openapi.json".to_owned(),
                ..Default::default()
            }),
        )
}

更多示例

• 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

• **问：我的（diesel）数据库没有实现 OpenApiFromRequest。**
  答：这是因为参数没有出现在路径、查询或体中。所以这被视为一个 请求守卫。有一个 派生宏 用于此，但它不能与 #[database("...")] 宏结合使用。您可以通过手动实现它来解决此问题，如下所示

use revolt_rocket_okapi::request::{OpenApiFromRequest, RequestHeaderInput};
use revolt_rocket_okapi::gen::OpenApiGenerator;
use rocket_sync_db_pools::{diesel, database};

#[database("sqlite_logs")]
pub struct MyDB;

impl<'r> OpenApiFromRequest<'r> for MyDB {
    fn from_request_input(
        _gen: &mut OpenApiGenerator,
        _name: String,
        _required: bool,
    ) -> revolt_rocket_okapi::Result<RequestHeaderInput> {
        Ok(RequestHeaderInput::None)
    }
}

• **问：...没有实现 JsonSchema？**
  答：JsonSchema 的实现由 Schemars 处理，请确保您为它启用了正确的 功能标志。如果它仍然没有实现，请向 Schemars 仓库打开一个问题。

• **问：我能在我的OpenAPI规范中添加自定义数据吗？**
  答：是的，请参阅 自定义模式 示例。Okapi 还内置了如果您想手动合并 OpenAPI 对象的功能。

• **问：我能否将此与Rocket以外的其他Web框架一起使用？**
  答：是的，但目前没有其他实现。但您可以使用独立的 Okapi crate 并使用Serde创建json或yaml文件。

功能标志

Okapi

• impl_json_schema：为 JsonSchema 和 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 支持。（当使用相同的功能标志时。）

请注意，并非所有来自 Schemars 的功能标志都被重新导出或启用。因此，如果您有未实现 JsonSchema 特性的对象，您可能需要在 Schemars 中启用一个功能标志。例如，请参阅 "uuid" 示例。（请确保 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 许可证。

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