HAP API 文档更新器

此技能专门用于维护和更新明道云 HAP (Host Application Platform) 的 OpenAPI 3.0 接口文档,支持中英文双语文档的同步管理。

使用场景

在以下情况下使用此技能:

• 用户需要在 HAP 文档中新增接口

• 用户需要修改现有接口的定义、参数或响应结构

• 用户需要删除废弃的接口

• 用户需要确保中英文文档保持同步

• 用户提到"HAP API 文档"、"接口文档"、"OpenAPI"、"新增接口"、"更新接口"等关键词

文档结构

HAP API 文档项目包含两类文档:

1. 组织授权 API 文档

位于项目根目录:

• en/

• 英文版组织授权接口文档

• zh-Hans/

• 中文版组织授权接口文档

2. 应用 API 文档 (v3-beta)

位于 application 目录:

• application/en/

• 英文版应用接口文档

• application/zh-Hans/

• 中文版应用接口文档

每个文档目录包含:

openapi.yaml # 主文件,定义 tags、paths 路由 description.md # 文档描述 index.html # Redoc 预览页面 paths/ # 接口定义目录 ├── user/ # 按功能模块分类 ├── department/ └── ... schemas/ # 数据模型目录 ├── base/ # 基础模型 ├── user/ # 用户相关模型 └── ...

工作流程

新增接口

确定接口类型和位置

• 询问用户接口属于哪个模块 (user/department/app 等)

• 确定是组织 API 还是应用 API

• 确定 HTTP 方法 (GET/POST/PUT/DELETE 等)

收集接口信息

• 接口路径 (如 /v2/user/getExternalPortalUsers )

• 接口摘要和描述

• 请求参数 (query/body/path parameters)

• 响应结构

• 是否需要鉴权参数 (appKey, sign, timestamp 等)

创建文件结构

对于每个语言版本 (en 和 zh-Hans),执行以下操作:

a. 创建 path 定义文件

• 位置: paths/{module}/{operationName}.yaml

• 包含: HTTP 方法、tags、summary、description、parameters/requestBody、responses

• 参考 references/path_template.yaml 中的模板

b. 创建 schema 文件 (如需要)

• 请求 schema: schemas/{module}/{operationName}Request.yaml

• 响应 schema: schemas/{module}/{operationName}Response.yaml

• 数据对象: schemas/{module}/{objectName}.yaml

• 参考 references/schema_template.yaml 中的模板

c. 更新 openapi.yaml

• 在 paths 部分添加新路由

• 如果有特殊的 server 配置,添加 servers 字段

• 确保按模块分组,保持文件整洁

验证一致性

• 确保中英文版本结构一致

• 检查所有 $ref 引用路径正确

• 验证必填字段在 required 数组中

修改接口

定位文件

• 使用 Grep 工具搜索接口路径或 operationId

• 找到对应的 path 文件和相关 schema 文件

同步修改

• 同时修改中英文版本的对应文件

• 保持字段结构一致,仅翻译 description 和 example

更新关联文件

• 如果修改了 schema 引用,检查其他使用该 schema 的接口

• 如果修改了路径,同步更新 openapi.yaml

删除接口

从 openapi.yaml 中移除路由

• 同时删除中英文版本

删除相关文件

• 删除 paths 文件

• 检查 schemas 是否被其他接口使用,如果没有则删除

验证引用

• 确保没有其他地方引用已删除的文件

同步中英文文档

对比结构

• 检查 openapi.yaml 中的 paths 是否一致

• 对比文件目录结构

同步差异

• 复制缺失的文件

• 翻译描述性文本

• 保持技术字段 (type, format, required 等) 完全一致

重要规范

命名规范

• 文件命名: 使用驼峰命名法,如 getExternalPortalUsers.yaml

• operationId: 与文件名保持一致

• schema 文件: 使用描述性名称,如 externalPortalUser.yaml

路径引用规范

• 从 openapi.yaml 引用 paths: './paths/{module}/{file}.yaml'

• 从 paths 引用 schemas: '../../schemas/{module}/{file}.yaml'

• 从 schemas 引用其他 schemas: './{file}.yaml'

请求/响应规范

GET 请求: 使用 parameters 定义查询参数

parameters:

• name: pageIndex in: query required: true schema: type: integer

POST 请求: 使用 requestBody 定义请求体

requestBody: required: true content: application/json: schema: $ref: '../../schemas/user/requestSchema.yaml'

鉴权参数

组织 API 通常需要以下基础参数:

• appKey

• 应用密钥

• sign

• 签名

• timestamp

• 时间戳

• projectId

• 项目 ID

可以引用基础 schema: $ref: ../../schemas/base/request/baseQueryAppkey.yaml

响应结构

标准响应格式:

type: object properties: code: type: integer description: 状态码,1表示成功 message: type: string description: 状态描述 data: type: object/array description: 返回数据

工作检查清单

在完成文档更新后,执行以下检查:

• 中英文版本都已更新

• openapi.yaml 中的路由已添加/修改/删除

• paths 文件已创建/修改/删除

• 必要的 schemas 文件已创建

• 所有 $ref 引用路径正确

• 必填参数在 required 数组中声明

• description 提供了清晰的说明

• example 提供了有效的示例值

• 中英文字段结构完全一致 (仅描述不同)

参考资料

详细的模板和示例请查看:

• references/path_templates.md

• 接口定义模板

• references/schema_templates.md

• 数据模型模板

• references/common_patterns.md

• 常见模式参考

预览文档

修改完成后,可以使用 Live Server 预览:

• 在 VS Code 中右键点击 zh-Hans/index.html 或 en/index.html

• 选择 "Open With Live Server"

• 浏览器将自动打开并显示 Redoc 渲染的文档