hap-api-doc-updater

HAP API Documentation Updater

This skill is dedicated to maintaining and updating the OpenAPI 3.0 interface documentation for Mingdao Cloud HAP (Host Application Platform), and supports synchronized management of Chinese and English bilingual documentation.

Use Cases

Use this skill in the following situations:

• The user needs to add an interface to the HAP documentation
• The user needs to modify the definition, parameters, or response structure of an existing interface
• The user needs to delete a deprecated interface
• The user needs to ensure that the Chinese and English documentation remain synchronized
• The user mentions keywords such as "HAP API documentation", "interface documentation", "OpenAPI", "add interface", "update interface", etc.

Documentation Structure

The HAP API documentation project contains two types of documentation:

1. Organization Authorization API Documentation

Located in the project root directory:

• en/ - English version organization authorization interface documentation
• zh-Hans/ - Chinese version organization authorization interface documentation

2. Application API Documentation (v3-beta)

Located in the application directory:

• application/en/ - English version application interface documentation
• application/zh-Hans/ - Chinese version application interface documentation

Each documentation directory contains:

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

Workflow

Add Interface

1. Determine the interface type and location

   • Ask the user which module the interface belongs to (user/department/app, etc.)
   • Determine whether it is an organization API or an application API
   • Determine the HTTP method (GET/POST/PUT/DELETE, etc.)

2. Collect interface information

   • Interface path (e.g., /v2/user/getExternalPortalUsers)
   • Interface summary and description
   • Request parameters (query/body/path parameters)
   • Response structure
   • Whether authentication parameters are required (appKey, sign, timestamp, etc.)

3. Create file structure

   For each language version (en and zh-Hans), perform the following operations:

   a. Create the path definition file

   • Location: paths/{module}/{operationName}.yaml
   • Include: HTTP method, tags, summary, description, parameters/requestBody, responses
   • Refer to references/path_template.yaml templates in

   b. Create schema files (if needed)

   • Request schema: schemas/{module}/{operationName}Request.yaml
   • Response schema: schemas/{module}/{operationName}Response.yaml
   • Data object: schemas/{module}/{objectName}.yaml
   • Refer to references/schema_template.yaml templates in

   c. Update openapi.yaml

   • Add the new route in the paths section
   • If there is a special server configuration, add the servers field
   • Ensure grouping by module and keep the file tidy

4. Verify consistency

   • Ensure the Chinese and English versions have a consistent structure
   • Check that all $ref reference paths are correct
   • Verify that required fields are in the required array

Modify Interface

1. Locate files

   • Use the Grep tool to search for the interface path or operationId
   • Find the corresponding path file and related schema files

2. Synchronize modifications

   • Also modify the corresponding files in the Chinese and English versions
   • Keep the field structure consistent, only translate description and example

3. Update related files

   • If a schema reference was modified, check other interfaces that use that schema
   • If a path was modified, synchronously update openapi.yaml

Delete an interface

1. Remove the route from openapi.yaml

   • Also delete the Chinese and English versions

2. Delete related files

   • Delete the paths file
   • Check whether the schemas are used by other interfaces; if not, delete them

3. Verify references

   • Ensure that no other places reference the deleted files

Synchronize the Chinese and English documentation

1. Compare the structure

   • Check whether the paths in openapi.yaml are consistent
   • Compare the file directory structure

2. Synchronize differences

   • Copy missing files
   • Translate descriptive text
   • Keep technical fields (type, format, required, etc.) completely consistent

Important specifications

Naming conventions

• File naming: Use camelCase naming, such as getExternalPortalUsers.yaml
• operationId: Keep consistent with the file name
• schema files: Use descriptive names, such as externalPortalUser.yaml

Path reference conventions

• Reference paths from openapi.yaml: './paths/{module}/{file}.yaml'
• Reference schemas from paths: '../../schemas/{module}/{file}.yaml'
• Reference other schemas from schemas: './{file}.yaml'

Request/response conventions

GET request: Use parameters to define query parameters

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

POST request: Use requestBody to define the request body

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

Authentication parameters

Organization APIs usually require the following basic parameters:

• appKey - App key
• sign - Signature
• timestamp - Timestamp
• projectId - Project ID

You can reference the base schema: $ref: ../../schemas/base/request/baseQueryAppkey.yaml

Response structure

Standard response format:

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

Work checklist

After completing the documentation updates, perform the following checks:

• Both the Chinese and English versions have been updated
• Routes in openapi.yaml have been added/modified/deleted
• Path files have been created/modified/deleted
• Necessary schema files have been created
• All $ref reference paths are correct
• Required parameters are declared in the required array
• description provides clear explanations
• example provides valid example values
• The Chinese and English field structures are completely consistent (only descriptions differ)

Reference materials

For detailed templates and examples, see:

• references/path_templates.md - API definition template
• references/schema_templates.md - Data model template
• references/common_patterns.md - Common patterns reference

Preview documentation

After modifications are complete, you can preview using Live Server:

1. In VS Code, right-click zh-Hans/index.html or en/index.html
2. Select "Open With Live Server"
3. The browser will open automatically and display the documentation rendered by Redoc