API Doc Writer

API接口文档助手。用于编写REST API文档、定义接口规范、生成接口说明。当需要编写API文档、接口规范时触发。

Security Scan

This is an instruction-only API documentation/template helper; it requests no credentials, installs nothing, and its runtime instructions are limited to generating doc text—what it declares matches what it does.

Purpose & Capability

Name and description (API doc writer) align with the SKILL.md content: templates, examples, and guidelines for REST API documentation. No unrelated capabilities or external services are requested.

Instruction Scope

SKILL.md contains only templates, examples, and design guidance for API docs. It does not instruct the agent to run commands, read files, access environment variables, or contact external endpoints.

Install Mechanism

No install spec or code files are present. Being instruction-only means nothing is written to disk or installed; this is the lowest-risk install model.

Credentials

The skill declares no required environment variables, credentials, or config paths. There is no disproportionate or unexplained secret access requested.

Persistence & Privilege

always:false and default invocation settings. The skill does not request persistent/system-level privileges or modifications to other skills or configs.

Assessment

This skill appears to be a harmless documentation/template helper and is internally consistent. Before installing, consider: (1) the source is unknown—prefer skills from trusted authors or with a homepage; (2) never paste real secrets or production tokens into sample requests/examples; (3) review generated docs for organization-specific policies (auth, error codes, naming conventions); (4) if the skill later asks for environment variables or to run code, re-evaluate permissions. Overall, it's low-risk as provided.

API接口文档助手

API文档模板

# API接口文档

版本：V1.0
更新日期：YYYY-MM-DD
维护人：XXX

---

## 接口概览

| 模块 | 接口数 | 负责人 |
|------|--------|--------|
| 用户模块 | 5 | @xxx |
| 订单模块 | 8 | @xxx |
| 支付模块 | 4 | @xxx |

---

## 通用说明

### 认证方式

Authorization: Bearer <token>

### 请求格式

Content-Type: application/json

### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}

状态码

状态码	说明
0	成功
1001	参数错误
2001	未授权
3001	资源不存在
5001	服务器错误

---

接口详情

1. 用户接口

1.1 获取用户信息

接口地址

GET /api/v1/users/{id}

请求参数

参数名	类型	位置	必填	说明
id	long	path	是	用户ID

请求示例

GET /api/v1/users/123

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "[e-mail]",
    "phone": "13800138000",
    "created_at": "2024-01-01 10:00:00"
  }
}

错误示例

{
  "code": 3001,
  "message": "用户不存在",
  "data": null
}

---

1.2 创建用户

接口地址

POST /api/v1/users

请求参数

参数名	类型	必填	说明
name	string	是	用户名
email	string	是	邮箱
phone	string	否	手机号
password	string	是	密码

请求示例

{
  "name": "张三",
  "email": "[e-mail]",
  "phone": "13800138000",
  "password": "123456"
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  }
}

---

2. 订单接口

2.1 订单列表

接口地址

GET /api/v1/orders

请求参数

参数名	类型	位置	必填	说明
page	int	query	否	页码，默认1
page_size	int	query	否	每页数量，默认20
status	string	query	否	订单状态

请求示例

GET /api/v1/orders?page=1&page_size=10&status=paid

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 10,
    "list": [
      {
        "id": "ORD202401010001",
        "user_id": 123,
        "amount": 100.00,
        "status": "paid",
        "created_at": "2024-01-01 10:00:00"
      }
    ]
  }
}

---

接口变更记录

版本	日期	变更内容	变更人
V1.0	YYYY-MM-DD	初始版本	@xxx
V1.1	YYYY-MM-DD	新增xxx接口	@xxx

## 接口设计原则

### RESTful规范
| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查询 | GET /users |
| POST | 创建 | POST /users |
| PUT | 完整更新 | PUT /users/1 |
| PATCH | 部分更新 | PATCH /users/1 |
| DELETE | 删除 | DELETE /users/1 |

### URL命名规范
```markdown
- 使用名词复数：/users
- 使用小写：/user-info
- 使用连字符分隔：/order-details
- 避免动词：不用 /getUser

状态码规范

类别	状态码	说明
1xx	信息	接收的请求正在处理
2xx	成功	请求正常处理完毕
3xx	重定向	需要附加操作完成请求
4xx	客户端错误	请求有语法错误
5xx	服务器错误	服务器处理出错

安全建议

• 敏感信息加密传输
• 身份验证Token过期机制
• 接口调用频率限制
• 参数校验过滤