API Doc Writer

Trigger Conditions

Use this skill when the task is to produce or revise an API interface document for product, frontend, QA, or integration readers.

Typical inputs:

• Existing backend code, controller/service implementation, OpenAPI notes, PRD, design notes, or a finished endpoint.
• A request to write a Feishu/Lark document, Markdown API document, or interface specification.
• Feedback that the current document contains too much backend implementation detail or that examples/fields need to be simplified.

Do not use this for implementation plans, backend design docs, code review reports, or internal debugging writeups.

Required Document Structure

Always use this top-level order:

1. 功能说明
2. 接口通用说明
3. 单个接口说明
4. 错误码说明

For multiple endpoints, repeat endpoint subsections under "3. 单个接口说明"; do not create a separate top-level section per endpoint.

Workflow

1. Collect the public contract.

   • Identify endpoint name, method, public path, base URL or environment URL, auth requirement, request headers, query/body parameters, response wrapper, data fields, and error codes.
   • If code is available, verify field names and response shape from DTO/controller/tests, not from guesses.
   • Separate public behavior from backend implementation details.

2. Write "1. 功能说明".

   • Start with a one-paragraph purpose statement.
   • Add "业务规则" as a table.
   • Include only rules that affect client behavior, display, validation, permission, limits, fallback, or user-visible semantics.

3. Write "2. 接口通用说明".

   • Include protocol, default base URL if known, request/response format, authentication method, response wrapper, unit conventions, pagination conventions, and common headers.
   • Keep environment-specific values clearly marked as examples or default test values.

4. Write "3. 单个接口说明".

   • For each endpoint include:
     • Basic info table: interface name, method, path, full example URL, login requirement.
     • Request parameters split by Header, Query, Path, and Body. Write "无" for absent parameter groups.
     • Response field table for data fields, with type and client-facing meaning.
     • A single "请求示例" subsection that combines curl command and scenario responses.

5. Write "4. 错误码说明".

   • Provide a table with code, meaning, trigger scenario, and client handling suggestion.
   • Include auth errors, validation errors, permission errors, and service errors only when they can occur for this API.
   • If the API falls back and still returns success, describe that behavior in business rules instead of inventing an error code.

6. Final pass.

   • Remove implementation file paths, class names, service names, Feign/client names, database table plans, test commands, build output, and backend verification notes unless the user explicitly asks for an engineering appendix.
   • Verify examples contain only fields that the API actually returns.
   • Check that no internal-only field, duplicated semantic field, placeholder token, private URL, account, or credential appears in the final document.

Hard Rules

• The document is an API contract, not an implementation report.
• Do not include backend file paths, modified file lists, compile commands, unit test commands, deployment notes, or internal call chains in the default output.
• Do not expose internal-only fields. If a field only explains how the server made a decision and the client does not need it, omit it.
• Do not duplicate field semantics. If limitBytes already communicates the effective quota, do not also expose fields like member, limitType, or action unless the real API returns them and the client has a use for them.
• Do not say "temporarily fixed", "not fully launched", or "not yet counted" when the client contract is a display rule. Prefer client-facing wording such as "when this field is -1, the client should not display the detailed value".
• Do not split examples into separate "成功用例", "失败用例", and "Curl 请求命令" sections. Merge them under one "请求示例" subsection.
• Do not invent request/response fields, status codes, or error codes. Mark unknowns as "待确认" only if they cannot be discovered.
• Do not include real access tokens, cookies, private account IDs, customer data, or private URLs. Use placeholders such as {access_token}, {domain}, and {id}.

Output Contract

When returning the document in chat or Markdown, output exactly these sections:

# <接口文档标题>

## 1. 功能说明

### 1.1 业务规则

## 2. 接口通用说明

### 2.1 通用响应结构

## 3. 单个接口说明

### 3.1 <接口名称>

#### 3.1.1 基本信息

#### 3.1.2 请求参数

#### 3.1.3 响应字段

#### 3.1.4 请求示例

## 4. 错误码说明

The "请求示例" subsection must include:

• one curl command;
• at least one success response;
• relevant failure responses such as unauthenticated, missing/invalid parameter, permission denied, or service exception when applicable.

Feishu/Lark Notes

When publishing to Feishu/Lark:

• Preserve the same four-section structure.
• Use tables for rules, parameters, response fields, and error codes.
• Use code blocks for curl and JSON examples.
• After update, fetch or search the remote document to confirm obsolete headings and removed fields are not still present.