Medusa OAS CLI 完全指南从 JSDoc 注解生成、校验到发布 OpenAPI 规范【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusaMedusa 开源仓库为开发者提供了一套名为medusajs/medusa-oas-cli的命令行工具它负责 Medusa 生态中所有与 OpenAPI SpecificationOAS相关的工作流扫描源码中的 JSDoc 注解自动编译出admin.oas.json、store.oas.json或合并后的combined.oas.json再经 Redocly 清洗、拆分与渲染为可发布的 API 文档。本文以官方 README 为主线结合仓库内真实源码、测试与默认配置完整讲解安装方式、oas与docs两大子命令的全部参数、底层执行链路与典型集成场景读完即可在本地或 CI 中复现 Medusa 官方的 API 文档生成流水线。工具定位Medusa 生态的 OAS 一站式 CLImedusa-oas-cli的定位在其 README 中写得很明确A command-line tool for all OpenAPI Specifications (OAS) related tooling即所有 OAS 相关工具的统一切入点。当前版本标注为0.1.0 - experimental仓库内package.json的发布版本为2.20.1说明其 API 仍处于演进期使用时应关注版本变更。从 src/index.ts 的入口实现可以看到CLI 采用commander构建程序名固定为medusa-oas默认挂载两个子命令oas—— 编译 OAS来自 command-oas.tsdocs—— 为 Redocly 文档查看器清洗 OAS来自 command-docs.ts未传入任何子命令时会输出帮助并报错退出同时两个子命令都开启了showHelpAfterError(true)参数写错时会自动回显帮助信息对新手相当友好。安装与首次配置安装命令yarn add --dev medusajs/medusa-oas-cli作为依赖安装后工具的可执行文件通过package.json的bin字段暴露为medusa-oas指向编译产物dist/index.js{ name: medusajs/medusa-oas-cli, bin: { medusa-oas: dist/index.js }, scripts: { build: yarn run -T tsc --build, medusa-oas: ts-node src/index.ts } }注意官方明确说明全局安装暂不支持README 中以删除线标注了npm install -g medusajs/medusa-oas-cli这一方式请勿使用。仓库内部则通过yarn run medusa-oas走ts-node src/index.ts直接执行源码见测试辅助函数runCLI的实现。配置 / 首次设置官方 README 给出的答案是N/A该工具无需任何环境变量、配置文件或初始化步骤装完即用。不过它有几个隐式的运行前提从源码可以确认依赖medusajs/medusa包见package.json的dependenciesoas命令需要解析它的路径来定位 JSDoc 扫描目录与包版本内部通过execa调用yarn redocly ...因此Redocly CLIredocly/cli1.25.3随包安装即可不必单独全局安装与 Medusa 官方 OAS 生成目录www/utils/generated/oas-output有约定路径关系仓库内开发--local模式依赖该目录存在。统一调用方式yarn medusa-oas command子命令一oas—— 编译 OAS工作原理oas命令的核心职责是扫描medusajs/medusa包把源码中的 JSDoc OAS 注解抽取并编译为一个 JSON 文件。底层使用swagger-inline库完成注解提取用readme/openapi-parser完成解析与校验整个流程在 command-oas.ts 的execute函数中串联。命令结束时会依据--type在当前目录输出admin.oas.json、store.oas.json或combined.oas.json三者之一。无效的 OAS 会直接抛错并阻止文件输出——除非显式传入--force。源码中的执行主流程已精简清晰地展现了收集 → 合并 → 打版本 → 校验 → 导出五段式管线let oas: OpenAPIObject if (apiType combined) { const adminOAS !local ? await getPublicOas(admin) : await getOASFromCodebase(admin) const storeOAS !local ? await getPublicOas(store) : await getOASFromCodebase(store) oas await combineOAS(adminOAS, storeOAS) } else { oas !local ? await getPublicOas(apiType) : await getOASFromCodebase(apiType) } if (additionalPaths.length || baseFile) { const customOAS await getOASFromPaths(additionalPaths, baseFile) if (baseFile) mergeBaseIntoOAS(oas, customOAS) if (additionalPaths.length) mergePathsAndSchemasIntoOAS(oas, customOAS) } setMedusaVersion(oas) await validateOAS(oas, apiType, force) if (dryRun) return await exportOASToJSON(oas, apiType, outDir)源码级实现细节值得关注的隐藏机制双数据源getOASFromCodebase从仓库内www/utils/generated/oas-output目录下的operations/{type}与schemas读取 JSDoc 注解错误相关的 schema 额外从medusajs/medusa/dist/utils/middlewares加载并以同名base/{type}.oas.base.yaml作为 swagger-inline 的 base而getPublicOas则直接从 Medusa 官方文档站点拉取公开 OAShttps://docs.medusajs.com/api/download/{type}。控制两者切换的正是源码中新增的--local选项README 中未收录仓库内测试大量使用用于 monorepo 内生成引用。版本注入setMedusaVersion会读取已安装的medusajs/medusa/package.json的version覆盖 OAS 中info.version。base 文件里的版本号只是静态占位符见 oas/default.oas.base.yaml 中的version: 1.0.0因此这一注入让下游消费者能准确识别 OAS 所描述的 Medusa 版本。强制模式validateOAS在默认情况下校验失败会process.exit(1)中断--force会跳过退出继续输出文件。--type string必填指定要生成哪份 API 的 OAS可取值admin、store、combined。源码中用.choices([...]).makeOptionMandatory()强制必选yarn medusa-oas oas --type adminadmin仅管理端 API/admin/*路由store仅商城端 API/store/*路由combined将 admin 与 store 两份 API合并为单一 OAS 文件。combined的合并策略定义在 src/utils/combine-oas.ts 中要点如下对 admin 与 store 两份 OAS 分别执行prepareOASForCombine给所有 tag 加上Admin/Store前缀如Admin Customer、Store Customer给所有operationId加上同样前缀如AdminGetCustomers、StoreGetCustomers避免命名冲突新建一个 OpenAPI 3.0.0 骨架依次合并paths、tags以及components下的九类子组件callbacks、examples、headers、links、parameters、requestBodies、responses、schemas、securitySchemes。测试验证在 command-oas.test.ts 中--type combined的用例断言了combined.oas.json同时包含/admin/products与/store/products、所有 tag 与 operationId 均以Admin/Store开头、且AdminProductsListRes与StoreProductsListRes两个 schema 都被合并进来。--out-dir path指定输出目录支持相对或绝对路径目录不存在会自动创建默认值为当前工作目录./yarn medusa-oas oas --type admin --out-dir ./oas对应源码outDir path.resolve(cliParams.outDir)且仅当非 dry-run 时执行mkdir(outDir, { recursive: true })。最终文件名为${apiType}.oas.json见exportOASToJSONpath.resolve(targetDir,${apiType}.oas.json)JSON 以 2 空格缩进格式化输出。--paths paths...传入额外的目录让工具去这些目录里爬取 JSDoc OAS 并合并进生成的 OAS。支持传入多个条目yarn medusa-oas oas --paths ~/medusa-server/src源码行为每个路径都会被path.resolve规范化并校验必须是目录否则抛出--paths must be a directory - path。随后getOASFromPaths用这些目录作为 swagger-inline 的扫描源默认 base 为 oas/default.oas.base.yaml最后通过mergePathsAndSchemasIntoOAS仅合并paths与components.schemas两类内容。典型用途你的自定义插件/模块里有独立于 Medusa 核心的 API 路由且已写好oasJSDoc就可以用它把自定义路由补进官方 OAS。测试用例演示了在临时目录中写入如下形式的 JSDoc 注解后调用--paths的场景/** oas [get] /foobar/tests * operationId: GetFoobarTests */ /** oas [get] /store/regions * operationId: OverwrittenOperation */ /** * schema FoobarTestSchema * type: object * properties: * foo: * type: string */测试断言新增的/foobar/tests路径与FoobarTestSchemaschema 会被加入且同名路径/同名 schema 会被覆盖/store/regions的 operationId 变为OverwrittenOperation。合并逻辑见 src/utils/merge-oas.ts 的mergePathsAndSchemasIntoOAS——Object.assign语义天然是后写覆盖先写。--base path用一个自定义的 OAS base 文件覆盖默认喂给 swagger-inline 的 base 内容。合并规则在 README 中明确给出Paths、tags 与 components 会执行合并其余 OAS 顶层属性如info、servers、security、externalDocs、webhooks、openapi版本会执行覆盖。yarn medusa-oas oas --base ~/medusa-server/oas/custom.oas.base.yaml对应实现mergeBaseIntoOASmerge-oas.ts替换策略openapi、info、servers、security、externalDocs、webhooks均以自定义 base 为准source ?? targettags 合并 去重同名 tag 以自定义 base 的版本覆盖新 tag 追加paths 合并Object.assign(target, source)同名路径被覆盖components 合并九个组件子类逐类Object.assign同名键被覆盖。测试用例--base分组用一个openapi: 3.1.0、自定义info/servers/security/externalDocs/webhooks、并带全套九类 components 的custom.oas.base.yaml验证了上述策略oas.openapi变为3.1.0、info变为{ version: 1.0.1, title: Custom API }、同名的Productstag 描述被覆盖、FoobarTag被新增、九个 components 分类全部被合并进来。--dry-run打包 OAS 但不输出文件专门用于校验 OAS 合法性yarn medusa-oas oas --dry-run源码逻辑execute中dryRun为真时跳过mkdir完成合并与版本注入后仍会执行validateOAS打印 Valid OAS 或 Invalid OAS随后打印⚫️ Dry run - no files generated并提前返回不触发exportOASToJSON。适合接入 CI 做文档健康度检查。--force忽略 OAS 校验错误强行输出生成的 OAS 文件yarn medusa-oas oas --force源码逻辑validateOAS捕获校验异常后打印 Invalid OAS默认process.exit(1)传入--force时则只记录错误、继续执行导出。注意它只能跳过校验失败JSDoc 语法本身的致命错误如--paths不是目录、--base不是文件仍会抛异常中断--base must be a file - path。选项速查表选项别名必填默认值说明--type type-t是无admin/store/combined决定输出文件名与 API 范围--out-dir path-o否当前目录输出目录不存在自动创建支持相对/绝对路径--dry-run-D否关闭只校验不落盘--paths paths...-p否无额外爬取 JSDoc 的目录可多个只合并 paths 与 schemas--base path-b否默认 base自定义 OAS base顶层属性覆盖、paths/tags/components 合并--force-F否关闭忽略校验错误继续输出--localREADME 未收录无否关闭从仓库内www/utils/generated/oas-output生成而非拉取公开 OAS子命令二docs—— 为 Redocly 清洗并产出文档工作原理docs命令的职责是对 OAS 进行清洗sanitize使其可用于 Redocly 的 API 文档查看器。从 command-docs.ts 看其内部通过execa依次调用 Redocly CLI 的bundle、split、preview-docs、build-docs子命令并在前后附加两层 Medusa 自研逻辑临时配置合并默认读取 redocly/redocly-config.yaml把plugins中相对路径的 medusa 插件替换为绝对路径若用户传入--config则用lodash.mergewith深合并数组采用 concat 拼接循环引用修复fixCirclularReferences先调用 Redocly 的bundle完成清洗再基于readme/openapi-parser检测残留的循环$ref将未被redocly-config.yaml中medusa/circular-patch覆盖的循环引用作为自动推荐补丁写回配置文件。处理链路为sanitizeOASredocly bundle→fixCirclularReferences循环引用补丁→ 按--split/--preview/--html分支产出。--src-file path必填指定源 OAS JSON 文件的路径yarn medusa-oas docs --src-file ./store.oas.json对应源码--src-file为必选项makeOptionMandatory路径经path.resolve处理。通常该文件就是oas子命令的产物。--out-dir path指定输出目录支持相对/绝对路径不存在会自动创建默认./yarn medusa-oas docs --src-file ./store.oas.json --out-dir ./docs非 dry-run 时执行mkdir(outDir, { recursive: true })。非--split模式下清洗后的 YAML 会写入${outDir}/openapi.yaml文件名由--main-file-name控制默认openapi.yaml。--config path指定 Redocly 配置文件路径yarn medusa-oas docs --src-file ./store.oas.json --config ./redocly-config.yaml源码对自定义配置文件有严格校验必须存在且扩展名必须是.json或.yaml否则抛出--config must be a file - path或--config file must be of type .json or .yaml - path。合并发生在mergeConfig以默认配置为底、自定义配置覆盖、数组字段 concat产物写入临时目录再交给 Redocly。默认配置内容可见 redocly/redocly-config.yaml其中核心的medusa/circular-patchdecorator 已内置数十条循环引用补丁如BaseProduct - BaseProductVariant、Order - OrderChange并包含 Redocly 主题样式暗色主色调、250px 侧边栏、隐藏下载按钮、按字母排序 tag 等。--dry-run只清洗不输出文件官方 README 特别指出其用途排查循环引用问题yarn medusa-oas docs --src-file ./store.oas.json --dry-run源码在 dry-run 分支中完成 sanitize 与循环引用修复后打印⚫️ Dry run - no files generated并通过git checkout还原可能被fixCirclularReferences自动改写的 redocly-config.yaml这正是该文件在 dry-run 下不会留下脏改动的保证。--clean生成前先清空目标目录yarn medusa-oas docs --src-file ./store.oas.json --clean源码shouldClean为真时执行fs.rm(outDir, { recursive: true, force: true })再重新mkdir。适合反复生成的 CI 场景避免陈旧文件残留。--split输出多文件结构内部调用 Redocly 的redocly splityarn medusa-oas docs --src-file ./store.oas.json --splitgenerateReference内部执行yarn redocly split src --outDiroutDir将单一 OAS 拆分为openapi.yaml主文件 components/paths/tags等目录的多文件结构便于版本管理和按需引用。仓库内www/apps/api-reference的规范文件即采用这类多文件组织。--preview在浏览器中打开 API 文档预览不输出文件内部调用redocly preview-docsyarn medusa-oas docs --src-file ../../../www/apps/api-reference/specs/store.oas.json --preview源码通过commandWrapper(previewDocs)启动本地服务端口8080、host127.0.0.1。注意该模式走完 sanitize 后即返回不落盘。--html生成零依赖的静态 HTML 文件内部调用redocly build-docsyarn medusa-oas docs --src-file ./store.oas.json --htmlbuildHTML内部执行yarn redocly build-docs src --outputoutDir/index.html --configconfig --cdntrue产出可直接静态托管的单文件文档页。源码中未收录于 README 的附加选项选项默认值说明--main-file-name nameopenapi.yaml非 split 模式下主 YAML 输出文件名命名与redocly split约定保持一致--archive-out-file path无将清洗后的完整 YAML 额外复制到指定路径自动创建中间目录用于版本化归档循环引用Circular Reference的处理机制Medusa 的数据模型大量存在双向关联如 Order ↔ OrderChange、BaseProduct ↔ BaseProductVariant直接在 Redocly 中渲染会触发$ref无限递归。docs命令的循环引用处理由两部分构成1. 声明式补丁decoratorredocly/plugins/medusa/decorators/circular-patch.js 中定义的medusa/circular-patchdecorator 按 redocly-config.yaml 中的schemas映射工作当解析器在特定 schema如Order内部遇到指向另一 schema 的$ref时把该$ref节点替换为内联的type: object描述${schemaName} object.从而切断递归链。2. 自动检测与回写fixCirclularReferences使用readme/openapi-parser以dereference: { circular: ignore }模式解析从$refs.circularRefs中提取所有循环引用点生成推荐补丁见 src/utils/circular-patch-utils.ts 的getCircularPatchRecommendation支持识别/items数组场景并将新发现的引用自动追加进redocly-config.yaml最后打印 Added the following unhandled circular references to redocly-config.ts提示。这就是为什么--dry-run会主动git checkout还原该配置文件——它会在运行中被自动修改。端到端工作流从 JSDoc 到在线 API 文档结合两个子命令一条完整的官方式 API 文档流水线是# 1. 编译 OAS输出 admin.oas.json / store.oas.json / combined.oas.json yarn medusa-oas oas --type combined --out-dir ./oas # 2. 清洗并生成多文件结构供文档站点引用 yarn medusa-oas docs --src-file ./oas/combined.oas.json --out-dir ./docs --split --clean # 3. 本地预览效果 yarn medusa-oas docs --src-file ./oas/combined.oas.json --preview # 4. 产出可静态托管的零依赖 HTML yarn medusa-oas docs --src-file ./oas/combined.oas.json --out-dir ./docs --html --clean在 CI 中推荐插入--dry-run步骤做校验门禁oas --dry-run负责验证 JSDoc 注解合法docs --dry-run负责验证循环引用是否全部被处理。仓库测试command-oas.test.ts 与 command-docs.test.ts对上述两条命令覆盖了admin/store 路由的隔离生成、combined 的 tag 与 operationId 前缀化、--paths/--base的合并覆盖语义、以及基于公开 OAS 的生成链路可作为理解工具行为边界的权威参考。实践建议与注意事项在自定义插件中管理 API 文档用--paths指向插件源码目录配合oasJSDoc 注解路由用oas [get] /pathschema 用schema即可让自定义端点进入官方生成的 OAS品牌化与版本化用--base提供自定义info、servers、security实现面向外部合作伙伴的定制 OASarchive-out-file与main-file-name适合做多版本 OAS 归档循环引用是常态而非异常Medusa 领域模型天然递归docs的自动补丁机制会持续维护redocly-config.yaml但该文件在--dry-run下会被自动还原请勿在同一会话中既 dry-run 又期望配置留存oas命令存在--local与公开 OAS 两条数据通路前者依赖 monorepo 内www/utils/generated/oas-output目录适用于仓库内开发后者从 Medusa 官方文档服务拉取适用于消费已发布版本该工具整体仍标记为 experimental升级medusajs/medusa等依赖时留意 CHANGELOG见 CHANGELOG.md避免选项行为变化影响 CI 流水线。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考