dev-api-doc-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Doc Generator

API文档生成器

Workflow

工作流程

Étape 1 — Détection du contexte

步骤1 — 上下文检测

Identifie avant tout :

Framework : Express/NestJS, FastAPI, Django REST, Laravel, ASP.NET Core, Spring Boot, etc.
Type d'API : REST, GraphQL, gRPC, WebSocket
Auth : Bearer JWT, API Key, OAuth2, Basic, aucune
Format cible : OpenAPI 3.1 YAML, Markdown, Postman Collection v2.1

Si aucun format cible n'est précisé, utilise OpenAPI 3.1 YAML pour une API REST, Markdown structuré sinon.

首先识别：

框架：Express/NestJS、FastAPI、Django REST、Laravel、ASP.NET Core、Spring Boot等
API类型：REST、GraphQL、gRPC、WebSocket
认证方式：Bearer JWT、API Key、OAuth2、Basic认证、无认证
目标格式：OpenAPI 3.1 YAML、Markdown、Postman Collection v2.1

如果未指定目标格式，REST API默认使用OpenAPI 3.1 YAML，其他类型则使用结构化Markdown。

Étape 2 — Extraction des endpoints

步骤2 — 端点提取

Pour chaque endpoint, collecte :

Champ	Contenu attendu
Méthode + URL	`POST /api/v1/payments`
Description	Action métier claire, pas le nom de la fonction
Path params	`{id}` → type, exemple, contraintes
Query params	nom, type, requis/optionnel, valeur par défaut
Request body	schéma JSON avec types, requis, exemples
Headers requis	`Authorization` , `Content-Type` , custom headers
Réponses	200/201/204 succès + 400/401/403/404/422/500 erreurs
Auth	scope/rôle requis si applicable

针对每个端点，收集以下信息：

字段	预期内容
方法 + URL	`POST /api/v1/payments`
描述	清晰的业务动作，而非函数名称
路径参数	`{id}` → 类型、示例、约束
查询参数	名称、类型、必填/可选、默认值
请求体	带类型、必填项、示例的JSON schema
必填请求头	`Authorization` 、 `Content-Type` 、自定义请求头
响应	200/201/204成功响应 + 400/401/403/404/422/500错误响应
认证	适用时需指定所需权限/角色

Étape 3 — Format de sortie

步骤3 — 输出格式

OpenAPI 3.1 YAML (format recommandé)

OpenAPI 3.1 YAML（推荐格式）

yaml

openapi: 3.1.0
info:
  title: Payments API
  version: 1.0.0
paths:
  /api/v1/payments:
    post:
      summary: Créer un paiement
      tags: [Payments]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency, recipient_id]
              properties:
                amount:
                  type: integer
                  description: Montant en centimes
                  example: 5000
                currency:
                  type: string
                  enum: [TND, EUR, USD]
                  example: TND
                recipient_id:
                  type: string
                  format: uuid
      responses:
        "201":
          description: Paiement créé
          content:
            application/json:
              example:
                id: "pay_abc123"
                status: "pending"
        "422":
          description: Validation échouée
          content:
            application/json:
              example:
                error: "amount must be positive"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

yaml

openapi: 3.1.0
info:
  title: Payments API
  version: 1.0.0
paths:
  /api/v1/payments:
    post:
      summary: Créer un paiement
      tags: [Payments]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency, recipient_id]
              properties:
                amount:
                  type: integer
                  description: Montant en centimes
                  example: 5000
                currency:
                  type: string
                  enum: [TND, EUR, USD]
                  example: TND
                recipient_id:
                  type: string
                  format: uuid
      responses:
        "201":
          description: Paiement créé
          content:
            application/json:
              example:
                id: "pay_abc123"
                status: "pending"
        "422":
          description: Validation échouée
          content:
            application/json:
              example:
                error: "amount must be positive"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Markdown structuré (si OpenAPI non requis)

结构化Markdown（若无需OpenAPI）

markdown

undefined

markdown

undefined

POST /api/v1/payments

Crée un nouveau paiement.

Auth : Bearer JWT requis (

role: operator

)

Body (application/json) :

Champ	Type	Requis	Description
amount	integer	oui	Montant en centimes
currency	string	oui	`TND` , `EUR` , `USD`
recipient_id	uuid	oui	ID du destinataire

Réponses :

— Paiement créé :

{ "id": "pay_abc123", "status": "pending" }

```
401
```
— Token manquant ou expiré

— Champ invalide :

{ "error": "amount must be positive" }

---

Crée un nouveau paiement.

Auth : Bearer JWT requis (

role: operator

)

Body (application/json) :

Champ	Type	Requis	Description
amount	integer	oui	Montant en centimes
currency	string	oui	`TND` , `EUR` , `USD`
recipient_id	uuid	oui	ID du destinataire

Réponses :

— Paiement créé :

{ "id": "pay_abc123", "status": "pending" }

```
401
```
— Token manquant ou expiré

— Champ invalide :

{ "error": "amount must be positive" }

---

Étape 4 — Exemples cURL copiables

步骤4 — 可复制的cURL示例

Génère un cURL par endpoint avec variables d'environnement :

bash

undefined

为每个端点生成带环境变量的cURL命令：

bash

undefined

Créer un paiement

curl -X POST "https://api.example.com/api/v1/payments"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{ "amount": 5000, "currency": "TND", "recipient_id": "550e8400-e29b-41d4-a716-446655440000" }'

---

---

Étape 5 — Table de synthèse

步骤5 — 汇总表

Produit toujours une table des routes en introduction :

Méthode	Endpoint	Auth	Description
GET	`/api/v1/payments`	JWT	Lister les paiements
POST	`/api/v1/payments`	JWT	Créer un paiement
GET	`/api/v1/payments/{id}`	JWT	Détail d'un paiement
DELETE	`/api/v1/payments/{id}`	JWT + admin	Annuler un paiement

始终在开头生成路由汇总表：

方法	端点	认证	描述
GET	`/api/v1/payments`	JWT	列出支付记录
POST	`/api/v1/payments`	JWT	创建支付记录
GET	`/api/v1/payments/{id}`	JWT	查看支付详情
DELETE	`/api/v1/payments/{id}`	JWT + admin	取消支付记录

Critères de décision — format

格式决策标准

Situation	Format recommandé
API publique / SDK tiers	OpenAPI 3.1 YAML + Swagger UI
Documentation interne équipe	Markdown structuré
Tests manuels / QA	Postman Collection v2.1
API GraphQL	SDL + descriptions de champs
Micro-service interne	OpenAPI minimal (pas de UI)

场景	推荐格式
公开API / 第三方SDK	OpenAPI 3.1 YAML + Swagger UI
团队内部文档	结构化Markdown
手动测试 / QA	Postman Collection v2.1
GraphQL API	SDL +字段描述
内部微服务	精简版OpenAPI（无需UI）

Pièges et anti-patterns

常见陷阱与反模式

Ne pas documenter les erreurs : documenter uniquement le 200 est insuffisant. Inclus systématiquement 401, 403, 422, 500.
Exemples irréalistes : évite
```
"string"
```
,
```
0
```
,
```
"id"
```
. Utilise des exemples métier (
```
"pay_abc123"
```
,
```
5000
```
,
```
"TND"
```
).
Oublier la pagination : si un endpoint retourne une liste, documente
```
page
```
,
```
limit
```
,
```
total
```
dans la réponse.
Nommer les paramètres ambigus :
```
id
```
seul est flou ; préfère
```
payment_id
```
,
```
user_id
```
.
Mélanger versions : OpenAPI 2.0 (Swagger) ≠ OpenAPI 3.0 ≠ 3.1. Reste cohérent dans tout le fichier.
Omettre les Content-Type : toujours préciser
```
application/json
```
ou
```
multipart/form-data
```
explicitement.
Description = nom de la fonction :
```
createPayment()
```
n'est pas une description ; écris l'action métier.

未记录错误响应：仅记录200响应是不够的，必须包含401、403、422、500错误响应。
示例不真实：避免使用
```
"string"
```
、
```
0
```
、
```
"id"
```
这类通用值，使用业务相关示例（如
```
"pay_abc123"
```
、
```
5000
```
、
```
"TND"
```
）。
遗漏分页信息：如果端点返回列表，需在响应中记录
```
page
```
、
```
limit
```
、
```
total
```
参数。
参数命名模糊：单独的
```
id
```
过于模糊，建议使用
```
payment_id
```
、
```
user_id
```
这类明确名称。
版本混用：OpenAPI 2.0（Swagger）≠ OpenAPI 3.0 ≠ 3.1，整个文档需保持版本一致。
遗漏Content-Type：需明确指定
```
application/json
```
或
```
multipart/form-data
```
。
描述等同于函数名：
```
createPayment()
```
不是有效描述，应编写业务动作说明。

Bonnes pratiques 2026

2026年最佳实践

Utilise OpenAPI 3.1 (aligné JSON Schema 2020-12) plutôt que 3.0.
Ajoute
```
x-stability: stable | beta | deprecated
```
sur chaque path pour signaler le niveau de maturité.
Génère des exemples nommés (
```
examples:
```
) plutôt que
```
example:
```
quand plusieurs cas existent (succès, erreur partielle, edge case).
Documente le rate limiting si présent : header
```
X-RateLimit-Limit
```
,
```
X-RateLimit-Remaining
```
.
Si code incomplet : documente ce qui est visible, marque les trous avec
```
# TODO: à compléter
```
dans le YAML.
Pour GraphQL : documente chaque Query/Mutation avec les arguments, types retournés et directives (
```
@auth
```
,
```
@deprecated
```
).

使用OpenAPI 3.1（与JSON Schema 2020-12对齐）而非3.0版本。
在每个路径上添加
```
x-stability: stable | beta | deprecated
```
字段，标记成熟度等级。
当存在多种场景（成功、部分错误、边缘情况）时，生成命名示例(
```
examples:
```
)而非单一示例(
```
example:
```
)。
若存在限流机制，需记录限流相关请求头：
```
X-RateLimit-Limit
```
、
```
X-RateLimit-Remaining
```
。
若代码不完整：记录可见内容，在YAML中用
```
# TODO: 待补充
```
标记缺失部分。
对于GraphQL：记录每个Query/Mutation的参数、返回类型及指令(
```
@auth
```
、
```
@deprecated
```
)。

Communication Rules — MANDATORY

沟通规则 — 强制要求

Ultra-concise. No filler, no preamble, no pleasantries.
Never say "happy to help", "sure!", "great question", "let me", or similar.
Tool first, talk second. Act before explaining.
Result first. Lead with outcome, not process.
Stop when done. No summary, no recap, no trailing commentary.
No politeness wrappers. Direct and blunt.
Minimum words. If one word works, do not use ten.
No unsolicited explanations.
No emoji unless asked.

极度简洁，无冗余内容、无开场白、无客套话。
禁止使用“很高兴帮忙”“没问题！”“好问题”“让我来”等类似表述。
先执行工具功能，再沟通。行动优先，解释在后。
结果优先。先展示结果，而非过程。
完成即停止。无需总结、回顾或额外评论。
无礼貌性修饰语。直接、坦率。
用词极简。能用一个词表达的，绝不使用十个词。
不主动提供解释。
除非被要求，否则不使用表情符号。