AdonisJS 集成指南用 adonis-autoswagger 自动生成 OpenAPI 并用 Scalar 渲染 API 参考文档【免费下载链接】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本文介绍如何在 TypeScript 全栈框架 AdonisJS 中接入 OpenAPI 文档体系借助社区包adonis-autoswagger自动把路由元数据编译成 OpenAPI 文件再利用其内置的 Scalar 集成AutoSwagger.default.scalar()以极小的代码量渲染出可交互的 API 参考页面。读完本文你将掌握完整的初始化流程、config/openapi.ts配置参数以及 Scalar CDN 构建在浏览器端挂载、解析配置、渲染文档的源码级实现链路。背景Scalar 与 AdonisJS 的集成方式AdonisJS 是一个 TypeScript 优先TypeScript-first的 Web 框架用于构建 Web 应用与 API 服务自带测试支持、现代工具链和丰富的官方生态包见 AdonisJS 集成文档。AdonisJS 与 Scalar 之间没有官方的一等集成的服务端中间件不像 Express、Fastify、NestJS 等框架有scalar/*-api-reference包而是通过社区生态打通社区包adonis-autoswagger负责为 AdonisJS 生成 OpenAPI 文档而它默认就内置了 Scalar API 参考的渲染能力。也就是说整条链路是AdonisJS 路由 ──(adonis-autoswagger)── OpenAPI (YAML) ──(Scalar CDN 构建)── 交互式 API 参考页面 服务端 /openapi 路由 /docs 路由本文以 AdonisJS 6即 AdonisJS 5 之后的最新主线为适用前提所有命令与文件结构均按该前提组织。第一步创建 AdonisJS 项目如果是全新项目先用官方脚手架初始化npm init adonisjslatest my-awesome-app脚手架会依次询问几个问题。如果一时拿不准可以按 AdonisJS 集成文档 推荐的本指南选项来选Which starter kit would you like to use? ❯ API Starter Kit Select the authentication guard you want to use … ❯ Access Token Select the database driver you want to use … ❯ SQLite Do you want us to install dependencies using npm? ❯ Yes其中 API Starter Kit 提供的是以 API 为核心的最小项目骨架Access Token 认证与 SQLite 则让本地跑起来零依赖外部服务。进入项目目录并启动开发服务器cd my-awesome-app npm run dev然后打开 http://localhost:3333 确认服务正常——AdonisJS 的开发服务器默认监听 3333 端口后文所有文档路由也都挂在这个端口上。已有 AdonisJS 项目可以跳过本步骤直接从第二步开始。第二步安装并配置 adonis-autoswagger安装npm add adonis-autoswagger配置文件config/openapi.tsadonis-autoswagger通过一个标准 AdonisJS 配置文件工作AdonisJS 6 的配置文件使用 ESM TypeScript放在config/目录下、以#config/别名导入。完整示例如下// config/openapi.ts import path from node:path import url from node:url export default { path: path.dirname(url.fileURLToPath(import.meta.url)) /../, title: My Awesome App, version: 1.0.0, snakeCase: true, tagIndex: 2, ignore: [/openapi, /docs], // If PUT/PATCH are provided for the same route, prefer PUT preferredPutPatch: PUT, common: { // OpenAPI conform parameters that are commonly used parameters: {}, // OpenAPI conform headers that are commonly used headers: {}, }, }配置参数说明参数示例值作用pathpath.dirname(url.fileURLToPath(import.meta.url)) /../项目根目录的绝对路径。由于配置文件位于config/子目录中这里借助 ESM 的import.meta.url反推出配置文件所在目录再上一级包用它来定位start/等目录、解析路由与控制器文件titleMy Awesome App写入 OpenAPIinfo.title的 API 标题version1.0.0写入 OpenAPIinfo.version的版本号snakeCasetrue是否将生成的 schema 字段名转换为 snake_casetagIndex2从配置项命名与用法推断其作用是指定以 URL 路径中的第几段作为 OpenAPI tag从而在参考页侧边栏中形成按路径前缀分组的目录结构ignore[/openapi, /docs]排除不需要出现在文档中的路由避免把文档自身的两个端点也收录进去preferredPutPatchPUT当同一路由同时提供 PUT 与 PATCH 时优先保留哪一种按注释语义默认偏好 PUTcommon.parameters{}全局通用的、符合 OpenAPI 规范的公共参数如统一的鉴权查询参数可合并到各端点上common.headers{}全局通用的、符合 OpenAPI 规范的公共响应头说明更多配置项及 AdonisJS 5 下的兼容用法请查阅adonis-autoswagger仓库的官方 README安装该包后node_modules/adonis-autoswagger内亦有完整文档。第三步挂载路由让 Scalar 渲染参考页真正“输出 OpenAPI 文件 渲染参考页”只需要扩展start/routes.ts两个路由// start/routes.ts import router from adonisjs/core/services/router import openapi from #config/openapi import AutoSwagger from adonis-autoswagger // Just an example route router.get(/, async () { return { hello: world, } }) // Returns the OpenAPI file as YAML router.get(/openapi, async () { return AutoSwagger.default.docs(router.toJSON(), openapi) }) // Renders the API reference with Scalar router.get(/docs, async () { return AutoSwagger.default.scalar(/openapi) })三个要点AutoSwagger.default.docs(router.toJSON(), openapi)把 AdonisJS 路由表的序列化结果router.toJSON()与#config/openapi配置一起传入在请求时动态编译出 OpenAPI 文档并以 YAML 格式返回。因为每次响应都基于当前路由表实时生成新增/修改路由后文档自动保持同步无需手动维护 spec 文件。AutoSwagger.default.scalar(/openapi)生成一段 HTML 页面其中嵌入 Scalar API 参考参数是 OpenAPI 文件的相对 URL。注意/docs传入的是相对路径/openapi——它指向同一个 AdonisJS 应用自己的端点浏览器同源加载不存在 CORS 问题也不需要代理。完成上述改动后访问 http://localhost:3333/docs就能看到基于 OpenAPI 的交互式参考页了。原理剖析/docs页面里 Scalar 是如何跑起来的AutoSwagger.default.scalar()输出的 HTML本质上就是 Scalar 的CDN 集成模式一个挂载容器 从 jsDelivr 加载scalar/api-reference独立构建的脚本 一段初始化调用。其形态与 HTML/JS 集成文档 描述的方式完全一致div idapp/div !-- 加载 scalar/api-reference 的 standalone 构建 -- script srchttps://cdn.jsdelivr.net/npm/scalar/api-reference/script !-- 初始化url 指向同源的 OpenAPI 端点 -- script Scalar.createApiReference(#app, { url: /openapi }) /script下面结合本仓库源码说明这条链路在浏览器端发生了什么。全局对象window.Scalar的注册CDN 脚本加载后执行 standalone 构建入口它先调用 registerGlobals()把createApiReference挂到window.Scalar上——这正是页面里能写Scalar.createApiReference(...)的原因// packages/api-reference/src/standalone/lib/register-globals.ts export const registerGlobals () { if (typeof window ! object) { return } // Initialize the global Scalar object window.Scalar { createApiReference, } }此外standalone 入口还会顺带扫描页面上遗留的 HTML contenteditable="false">【免费下载链接】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），仅供参考