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/ - 中文版应用接口文档

每个文档目录包含:

code

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 定义查询参数

yaml

parameters:
  - name: pageIndex
    in: query
    required: true
    schema:
      type: integer

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

yaml

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

响应结构

标准响应格式:

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 渲染的文档