用途:在修改 API 端点或 Schema 时,强制保持 Swagger 文档同步。任何 API 端点架构的变更都必须反映到 Swagger 文档中,未更新 Swagger 前不得视为 API 变更完成。
适用场景:修改 front/pages/api/** 或 front/app/api/** 下的文件;在请求/响应体中任意嵌套层级新增、删除或重命名字段;改变 API Schema 中字段类型或可选性;新增或删除端点时,该规则自动生效。
需要更新的内容:修改 API Schema 时,检查并更新 pages/api/swagger_private_schemas.ts(私有 API 共享 Schema)、pages/api/v1/w/[wId]/swagger_schemas.ts(公共 API 共享 Schema),以及端点文件本身的 @swagger 注解。
注解要求:每个端点必须带有 @swagger 注解(含完整文档)或 @ignoreswagger(用于内部/不公开端点),由 lint:swagger-annotations 检查强制执行。使用 @swaggerschema 标注的 TypeScript 类型指向对应的 Swagger Schema,修改此类类型时必须同步更新所引用的 Schema。
流程:进行 API/类型变更;确定哪些 Swagger 文件引用了被修改的 Schema;更新所有相关的 @swagger 注解与共享 Schema 文件;确认 lint:swagger-annotations 通过。该技能无需手动调用,任何 API 相关工作都应自动遵循这些规范。
限制:资料未提供具体命令、安装方式、平台与收费信息。