backend-api-documenter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Backend API Documenter

后端API文档生成工具

Generate comprehensive backend API documentation by reading FastAPI route files and schema definitions, then creating detailed specifications in

backend/AGENTS.md

通过读取FastAPI路由文件和Schema定义，生成完整的后端API文档，然后写入详细的规范到

backend/AGENTS.md

中。

Core Workflow

核心工作流程

1. Scan API Structure

1. 扫描API结构

Read all backend API route files to identify:

API modules and their base paths
All endpoints (GET, POST, PUT, PATCH, DELETE)
Route decorators and parameters
Summary and description annotations

Key files to read:

```
backend/app/api/v1/*.py
```
- All API route files
```
backend/app/schemas/*.py
```
- Request/response schema definitions
```
backend/CLAUDE.md
```
- Backend-specific specifications (if exists)

Optional helper script:

bash

python3 scripts/scan_api_routes.py ./backend

读取所有后端API路由文件，识别：

API模块及其基础路径
所有接口（GET、POST、PUT、PATCH、DELETE）
路由装饰器和参数
摘要和描述注解

需读取的关键文件：

```
backend/app/api/v1/*.py
```
- 所有API路由文件
```
backend/app/schemas/*.py
```
- 请求/响应Schema定义
```
backend/CLAUDE.md
```
- 后端专属规范（如果存在）

可选辅助脚本：

bash

python3 scripts/scan_api_routes.py ./backend

2. Extract Endpoint Details

2. 提取接口详情

For each endpoint, extract:

HTTP method and path
Request headers (Authorization, X-API-Key, etc.)
Request body schema (from Pydantic models)
Response body schema
Query parameters
Path parameters
Error responses and status codes
Business rules from docstrings and code logic

针对每个接口，提取：

HTTP方法和路径
请求头（Authorization、X-API-Key等）
请求体Schema（来自Pydantic模型）
响应体Schema
查询参数
路径参数
错误响应和状态码
来自文档字符串和代码逻辑的业务规则

3. Organize Documentation

3. 组织文档结构

Structure documentation following this hierarchy:

1. Module Overview
   Base路径: /api/v1/module

   1.1 Endpoint Name
   - 接口 (Interface)
   - 描述 (Description)
   - 请求头 (Request Headers)
   - 请求体 (Request Body) with field descriptions
   - 响应体 (Response Body) with field descriptions
   - 错误响应 (Error Responses)
   - 权限要求 (Authorization)
   - 业务规则 (Business Rules)

按照以下层级组织文档：

1. 模块概述
   基础路径: /api/v1/module

   1.1 接口名称
   - 接口（Interface）
   - 描述（Description）
   - 请求头（Request Headers）
   - 请求体（Request Body）及字段说明
   - 响应体（Response Body）及字段说明
   - 错误响应（Error Responses）
   - 权限要求（Authorization）
   - 业务规则（Business Rules）

4. Include Standard Appendices

4. 包含标准附录

Always include these appendices at the end:

附录A: 统一响应格式 - Standard response format and business codes
附录B: 国际化支持 - i18n headers and locale handling
附录C: 认证方式 - JWT Token and API Key authentication
附录D: 错误处理最佳实践 - Client-side error handling patterns

See doc_template.md for complete template structure.

文档末尾必须包含以下附录：

附录A: 统一响应格式 - 标准响应格式和业务码
附录B: 国际化支持 - i18n请求头和区域处理
附录C: 认证方式 - JWT Token和API Key认证
附录D: 错误处理最佳实践 - 客户端错误处理模式

完整模板结构请参考doc_template.md。

5. Write Documentation

5. 写入文档

Write the complete documentation to

backend/AGENTS.md

Start with project context inheritance:

> **Inherits from**: [Root AGENTS.md](../AGENTS.md)

Include table of contents with anchor links
Use consistent formatting (Chinese labels, English technical terms)
Provide concrete JSON examples for all requests/responses
Document all field types, constraints, and validation rules
Include business logic and special cases

将完整文档写入

backend/AGENTS.md

：

开头添加项目上下文继承：

> **继承自**: [Root AGENTS.md](../AGENTS.md)

包含带锚点链接的目录
使用统一格式（中文标签+英文技术术语）
为所有请求/响应提供具体JSON示例
记录所有字段类型、约束和验证规则
包含业务逻辑和特殊场景

Field Description Best Practices

字段说明最佳实践

For every field in request/response schemas, document:

Name and type:
```
field_name
```
(string, int, float, bool, array, object)
Required/Optional: Always specify
Constraints: Length limits, value ranges, formats, enums
Description: What it represents and how it's used
Examples: Concrete values when helpful

Example:

markdown

- `email` (string, optional): User email address, must be valid email format, max 255 characters
- `reward_amount` (float, required): Task reward amount, must be > 0, max 100000
- `status` (string, required): Task status, possible values: published/in_progress/completed/expired
- `location` (object, optional): GeoJSON Point format with coordinates [longitude, latitude]

对于请求/响应Schema中的每个字段，需记录：

名称和类型:
```
field_name
```
(string, int, float, bool, array, object)
必填/可选: 必须明确标注
约束: 长度限制、取值范围、格式、枚举值
描述: 字段含义及使用方式
示例: 必要时提供具体取值示例

示例：

markdown

- `email` (string, 可选): 用户邮箱地址，必须符合有效邮箱格式，最大长度255字符
- `reward_amount` (float, 必填): 任务奖励金额，必须>0，最大值100000
- `status` (string, 必填): 任务状态，可选值: published/in_progress/completed/expired
- `location` (object, 可选): GeoJSON Point格式，坐标为[经度, 纬度]

Common Patterns

常见模式

Authentication Documentation

认证文档示例

markdown

**请求头**:

Authorization: Bearer {access_token}

或

X-API-Key: {api_key}


**权限要求**: 需要人类用户认证(JWT Token) 或 需要代理认证(API Key)

markdown

**请求头**:

Authorization: Bearer {access_token}

或

X-API-Key: {api_key}


**权限要求**: 需要人类用户认证(JWT Token) 或 需要代理认证(API Key)

Error Response Documentation

错误响应文档示例

markdown

**错误响应**:

验证失败(400):
```json
{
  "success": false,
  "code": "INVALID_INPUT",
  "message": "输入参数无效",
  "data": null
}

未授权(401):

json

{
  "success": false,
  "code": "UNAUTHORIZED",
  "message": "未授权",
  "data": null
}

undefined

markdown

**错误响应**:

验证失败(400):
```json
{
  "success": false,
  "code": "INVALID_INPUT",
  "message": "输入参数无效",
  "data": null
}

未授权(401):

json

{
  "success": false,
  "code": "UNAUTHORIZED",
  "message": "未授权",
  "data": null
}

undefined

Business Rules Documentation

业务规则文档示例

markdown

**业务规则**:
- 只有任务所有者可以更新
- 创建任务时会锁定相应金额
- 任务发布后立即可见
- 评分范围: 1.0-5.0

markdown

**业务规则**:
- 只有任务所有者可以更新
- 创建任务时会锁定相应金额
- 任务发布后立即可见
- 评分范围: 1.0-5.0

Documentation Quality Standards

文档质量标准

Completeness: Document every field in every request/response
Accuracy: Match actual code behavior, not ideal behavior
Clarity: Use clear, concise language with concrete examples
Consistency: Follow same format for all endpoints
Bilingual: Chinese labels with English technical terms
Currency: Keep documentation in sync with code changes

完整性: 记录所有请求/响应中的每个字段
准确性: 与实际代码行为一致，而非理想行为
清晰性: 使用简洁明了的语言并提供具体示例
一致性: 所有接口遵循相同格式
双语性: 中文标签搭配英文技术术语
时效性: 文档需与代码变更保持同步

Notes

注意事项

This skill generates documentation for FastAPI-based backends
Assumes Pydantic models for request/response schemas
Follows unified response format with success/code/message/data structure
Supports both JWT Token (human users) and API Key (agents) authentication
Documentation should be comprehensive but concise - include all necessary details without redundancy

本技能为基于FastAPI的后端生成文档
假设使用Pydantic模型定义请求/响应Schema
遵循包含success/code/message/data结构的统一响应格式
支持JWT Token（人类用户）和API Key（代理）两种认证方式
文档需全面且简洁 - 包含所有必要细节，避免冗余