在 Axum 中内嵌 Scalar API Referencescalar_api_reference Rust Crate 完整实战指南【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本篇指南聚焦 Scalar 官方的 Rust 集成文档 Axum 集成说明讲解如何使用scalar_api_referencecrate 在 Axum Web 应用中零前端依赖地渲染 OpenAPI 交互文档。读完后你将掌握该 crate 的依赖配置、router/routes/scalar_response三档 API 的适用场景与底层实现机制资源内嵌、HTML 模板注入、JS Bundle 加载策略并知道如何为文档启用 Agent AI 聊天能力。工作原理把 UI 直接编译进二进制在深入 API 用法前先理解该 crate 的核心设计——从源码 integrations/rust/src/lib.rs 可以看到它通过rust-embed把ui/目录下的静态资源直接嵌入 Rust 二进制#[derive(RustEmbed)] #[folder ui/] struct Assets;这意味着你的 Axum 服务不依赖外部 CDN、也不需要在项目里维护前端文件发布一个二进制即可完整交付文档页面。嵌入的入口模板 ui/index.html 只有 20 多行核心是两个占位符div idapp/div script src__JS_BUNDLE_URL__/script script Scalar.createApiReference(#app, __CONFIGURATION__) /scriptcrate 的render_scalar函数会做两件事把你的配置 JSON 注入__CONFIGURATION__占位符再把 JS Bundle 地址注入__JS_BUNDLE_URL__占位符。如果未显式指定 Bundle 地址默认回退到 CDN 上的scalar/api-reference包而通过框架集成函数如router传入的Some({path}/scalar.js)则指向内嵌资源由 crate 自身路由分发。这一机制由 lib.rs 中的单元测试 明确验证js_bundle_url传Some时 HTML 中应包含自定义路径传None时则包含 CDN 地址。安装在 Cargo.toml 中启用 axum feature按集成文档在你的Cargo.toml中添加如下依赖[dependencies] scalar_api_reference { version 0.1.0, features [axum] } axum 0.7 serde_json 1.0 tokio { version 1.0, features [full] }关于版本有两点从仓库中可以确认的适用前提该 crate 以 feature 方式隔离框架依赖axum、actix-web、warp三个 feature 互不干扰见 integrations/rust/Cargo.toml。不启用任何 feature 时你可以只使用框架无关的核心函数scalar_html、get_asset等。从 crate 的Cargo.toml结构看其axumfeature 实际依赖axum 0.8.x与axum-extra 0.12.x且 crate 自身版本已随 CHANGELOG 迭代到 0.2.x。集成文档示例中写的0.1.0是历史起步版本实际接入时建议以 crates.io 上的最新版本为准并保持你应用中的 axum 版本与 crate 所依赖的 axum 版本兼容。快速上手一行 router() 生成文档路由最小可用的 Axum 示例如下与 examples/axum.rs 一致后者额外演示了theme配置项use axum::{Router}; use scalar_api_reference::axum::router; use serde_json::json; #[tokio::main] async fn main() { let configuration json!({ // URL to your OpenAPI document url: https://registry.scalar.com/scalar/apis/galaxy?formatjson, }); let app Router::new() .merge(router(/scalar, configuration)); let listener tokio::net::TcpListener::bind(0.0.0.0:3000).await.unwrap(); println!(Server running on http://localhost:3000/scalar); axum::serve(listener, app).await.unwrap(); }router(/scalar, configuration)一次性注册了两条路由。对照 lib.rs 中router的实现文档页GET /scalar返回scalar_response即以Some(/scalar/scalar.js)为 Bundle 地址渲染的 HTML——页面引用的是内嵌 JS 而非 CDN资源页GET /scalar/scalar.js通过get_asset_with_mime(scalar.js)从二进制内取出发出附带application/javascript的 Content-Type资源缺失时返回 404。configuration是一个普通的serde_json::Value其中的字段会原样注入前端模板支持所有标准 Scalar 配置项例如urlOpenAPI 文档地址可以是绝对 URL也可以是你自己暴露的相对路径如/openapi.json、theme、layoutclassic或modern、darkMode等。完整字段说明见 配置参考文档 与 Rust 集成总览。需要更细粒度的路由控制routes() 拆分两条路由如果你的应用需要对两条路由做差异化处理例如给文档页加认证中间件、给资源页加缓存头可以使用routes函数把两个Router拆开返回use scalar_api_reference::axum::{routes}; let (scalar_route, asset_route) routes(/scalar, configuration); let app Router::new() .merge(scalar_route) .merge(asset_route);从源码看routes与router的内部逻辑完全一致只是将文档路由与 JS 资源路由分别包装成独立的Router返回方便你在Router::nest、中间件分层等场景下单独挂载。只想要响应体不想托管路由scalar_response若你已经有自己的路由与响应构造逻辑可以绕过 crate 的路由封装直接生成 HTML 响应use scalar_api_reference::axum::scalar_response; use axum::response::Html; use serde_json::json; // Create a response handler async fn scalar_handler() - HtmlString { let configuration json!({ url: /openapi.json, }); scalar_response(configuration, Some(/scalar/scalar.js)) }第二个参数js_bundle_url的取值决定资源加载方式传Some(/scalar/scalar.js)HTML 引用你自行或经由asset_route分发的内嵌 JS离线可用传NoneHTML 回退到 CDN 上的scalar/api-reference省去自己托管静态资源但页面渲染依赖外网可达。同系列还提供scalar_response_from_json直接从 JSON 字符串构造响应并返回ResultHtmlString, serde_json::Error非法 JSON 会得到显式错误而非静默失败——这一行为有对应测试覆盖见 lib.rs 的 axum_tests 模块。此外即使不启用axumfeaturecrate 也暴露了框架无关的scalar_html/scalar_html_default/get_asset/get_asset_with_mime核心函数你可以在任意 Web 框架中自行拼装响应用法见 Rust 集成总览文档。启用 Agent为文档页添加 AI 聊天Scalar 的 Agent 功能会在文档页内置一个 AI 聊天界面。按 Axum 集成文档 的说明在 localhost 上 Agent 默认以受限免费额度可用要在生产环境启用需要在配置中加入 API Keylet configuration json!({ url: https://registry.scalar.com/scalar/apis/galaxy?formatjson, agent: { key: your-agent-scalar-key } });要彻底关闭 Agent则显式设置 disabledlet configuration json!({ url: /openapi.json, agent: { disabled: true } });更完整的 Agent 配置规则包括按文档粒度配置 Key见 Rust 集成总览中的 Agent 章节。值得一提的是crate 在 integrations/rust/src/config.rs 中还提供了类型安全的配置构造器可以先用强类型对象拼装、再序列化进Valueuse scalar_api_reference::{AgentOptions, Source}; use serde_json::json; // 顶层 Agent Key let config json!({ url: /openapi.json, agent: serde_json::to_value(AgentOptions::with_key(your-agent-scalar-key)).unwrap() }); // 显式禁用 let config json!({ url: /openapi.json, agent: serde_json::to_value(AgentOptions::disabled()).unwrap() }); // 多文档sources场景下为单个文档配置 Agent let sources vec![ Source::new(https://api.example.com/v1.json).with_agent(AgentOptions::with_key(key-for-v1)), Source::new(https://api.example.com/v2.json), ]; let config json!({ sources: serde_json::to_value(sources).unwrap() });AgentOptions序列化为 camelCase JSONkey与disabled字段均为Option为空时不会出现在最终 JSON 中避免向前端注入冗余字段。这套行为有测试用例验证见 lib.rs 的 test_agent_options_in_config。静态资源分发与 MIME 处理文档页依赖的scalar.js由 crate 内置get_asset_with_mime负责取出字节流并推断 Content-Type。从 get_mime_type 的实现 可以看到内置的扩展名映射html → text/html、js → application/javascript、css → text/css、json → application/json、png/svg/ico → 对应图片类型未知扩展名兜底为application/octet-stream。如果你的项目需要分发ui/目录中的其他资源例如自行定制的主题文件可以直接调用get_asset拿到字节内容后按自己的规则下发。小结三种 API 的选型建议场景推荐 API说明标准挂载、最少代码axum::router自动注册文档页 内嵌 JS 资源两条路由需要独立中间件/分层挂载axum::routes返回两个独立Router分别合并已有路由体系只要响应体axum::scalar_response返回HtmlStringBundle 地址自行决定非 Axum 框架scalar_html/get_asset*框架无关核心函数整体接入路径为添加带axumfeature 的依赖 → 构造configurationJSON含url及可选的theme、agent等字段→ 用上述三档 API 之一挂载到你的Router。所有关键行为占位符注入、默认 CDN 回退、资源 MIME、非法 JSON 报错在 integrations/rust/src/lib.rs 的测试模块中均有断言覆盖可作为你二次集成时的行为基线。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考