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]: 将添加更多示例，如果您有好的示例，请提交 issue。

基本用法

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 Web 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规范添加自定义数据吗？**
  答：是的，请参阅 自定义模式 示例。如果需要手动合并 OpenAPI 对象，Okapi还内置了功能。

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

功能标志

Okapi

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

请注意，并非所有来自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包含派生宏的代码。#[openapi]，rocket_okapi::openapi_spec![...]，rocket_okapi::openapi_routes![...]和#[derive(OpenApiFromRequest)]在我们的例子中。由于Rust的限制，这需要在单独的crate中。注意：derive或codegen crate通常比其他crate难处理。因此，在更改此处之前，建议先获得一些关于派生宏如何工作的经验。

待办事项

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

许可证

本项目采用 MIT 许可证。

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