utoipa-redoc

该包作为 utoipa 和 Redoc OpenAPI 可视化工具之间的桥梁。

utoipa-redoc 提供了一种简单的机制，将 OpenAPI 规范资源转换为可服务的 HTML 文件，该文件可以通过 预定义框架集成 或通过手动方式在您喜爱的 Web 框架中通过 HTTP 处理器提供。

您可以从 utoipa 的 Github 仓库 中找到完整示例。

包功能

• actix-web 允许通过 actix-web 提供服务。 version >= 4
• rocket 允许通过 rocket 提供服务。 version >=0.5
• axum 允许通过 axum 提供服务。 version >=0.7

安装

仅使用 Redoc 而不使用任何样板实现。

[dependencies]
utoipa-redoc = "4"

启用与 Redoc 的 actix-web 集成。

[dependencies]
utoipa-redoc = { version = "4", features = ["actix-web"] }

独立使用

utoipa-redoc 可以作为独立工具使用，只需创建一个新的 Redoc 实例，然后通过您喜爱的 Web 框架中的 HTTP 处理器以 text/html 的方式提供。

可以使用 Redoc::to_html 方法将 Redoc 实例转换为可服务的 HTML 文件。

let redoc = Redoc::new(ApiDoc::openapi());

// Then somewhere in your application that handles http operation.
// Make sure you return correct content type `text/html`.
let redoc_handler = move || async {
    redoc.to_html()
};

自定义

utoipa-redoc 支持根据可由修改 HTML 模板和 配置选项 定制的 Redoc。

默认的HTML模板可以通过Redoc::custom_html方法完全覆盖，以满足您的喜好。HTML模板必须包含$spec和$config变量，这些变量将在Redoc::to_html执行期间被替换。

• $spec将是将通过Redoc渲染的Spec。
• $config将是当前的Config。默认情况下，这是EmptyConfig。

使用自定义模板覆盖HTML模板。

let html = "...";
Redoc::new(ApiDoc::openapi()).custom_html(html);

配置

Redoc可以通过JSON进行配置，可以是内联的Redoc声明，也可以是从用户定义的文件中加载的FileConfig。

• 所有支持的Redoc配置选项.

内联配置。

Redoc::with_config(ApiDoc::openapi(), || json!({ "disableSearch": true }));

使用FileConfig。

Redoc::with_config(ApiDoc::openapi(), FileConfig);

在Config中了解更多详情。

示例

通过actix-web框架提供Redoc服务。

use actix_web::App;
use utoipa_redoc::{Redoc, Servable};

App::new().service(Redoc::with_url("/redoc", ApiDoc::openapi()));

通过rocket框架提供Redoc服务。

use utoipa_redoc::{Redoc, Servable};

rocket::build()
    .mount(
        "/",
        Redoc::with_url("/redoc", ApiDoc::openapi()),
    );

通过axum框架提供Redoc服务。

use axum::Router;
use utoipa_redoc::{Redoc, Servable};

let app = Router::<S>::new()
    .merge(Redoc::with_url("/redoc", ApiDoc::openapi()));

使用Redoc通过url提供OpenAPI规范。

Redoc::new(
  "https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml")

使用serde的json!()宏提供自定义OpenAPI规范。

Redoc::new(json!({"openapi": "3.1.0"}));

许可

根据您的选择，许可协议为Apache 2.0或MIT。

除非您明确声明，否则您有意提交以包含在本crate中的任何贡献，都应双许可，没有任何额外的条款或条件。