用途:在基于 open_api_spex 的 Phoenix 应用中管理 OpenAPI 规范,通过 /openapi [子命令] 调用。
主要能力:提供 regenerate 与 help 两个子命令。regenerate 从控制器操作和 schema 模块重新生成 OpenAPI 规范;help 输出可用子命令列表。不带子命令时默认执行 regenerate,未知子命令则列出可用项后停止。
使用方式:先查找实现 @behaviour OpenApiSpex.OpenApi 的 ApiSpec 模块(通常为 <App>Web.ApiSpec),可用 grep -r "@behaviour OpenApiSpex.OpenApi" lib/ --include="*.ex" 搜索。再检查项目根目录是否已有 openapi.json 或 openapi.yaml 以确定格式。生成命令:JSON 用 mix openapi.spec.json --spec <App>Web.ApiSpec,YAML 用 mix openapi.spec.yaml --spec <App>Web.ApiSpec。两种格式都存在则都生成,都不存在默认 JSON。生成后用 git diff openapi.json 对比变更,报告新增/删除的端点与 schema 变化,无变化则说明已是最新。
规范来源:ApiSpec 模块定义元数据、服务器与安全方案并调用 Paths.from_router(Router);控制器操作通过 OpenApiSpex.operation/2 或 ControllerSpecs DSL 声明参数、请求体与响应;schema 模块实现 OpenApiSpex.Schema。
限制与注意:规范在编译期从实际代码生成,若 mix 任务因编译错误失败,需先修复源码。缺少 operation 回调或 @doc operation: 注解的控制器动作不会出现在规范中;Ecto schema 变更而 API schema 未同步会导致规范过时。YAML 格式依赖 ymlr,需添加 {:ymlr, "~> 5.0"}。生成的规范文件应提交版本控制。若应用未配置 open_api_spex,则无法使用。