Okapi

Okapi:

Rocket-Okapi:

为 Rust/Rocket 项目自动生成 OpenAPI (又称 Swagger) 文档。

不再有过时的文档。Okapi 在设置服务器时会为您生成文档。它结合了 Rust Doc 注释 和编程逻辑来记录您的 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。
• 特殊类型：展示一些不太常见的类型及其使用。 (仍在开发中)

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)
    }
}