adding-api-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Use this skill when the user asks to add API docs, Swagger, OpenAPI spec, or generate endpoint documentation.

当用户要求添加API文档、Swagger、OpenAPI规范或生成端点文档时，使用此技能。

Detect the API framework — check for Express, Fastify, Next.js API routes, Hono, Django REST Framework, FastAPI, etc.

For Node.js/Express — install

swagger-jsdoc

and

swagger-ui-express

bash

npm install swagger-jsdoc swagger-ui-express
npm install -D @types/swagger-jsdoc @types/swagger-ui-express

Create the OpenAPI spec from JSDoc annotations on route handlers:

/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: List all users
 *     responses:
 *       200:
 *         description: A list of users
 */

For Next.js API routes — create an
```
openapi.json
```
file manually or use
```
next-swagger-doc
```
to generate from route handlers. Serve the spec at
```
/api/docs
```
.
For FastAPI (Python) — docs are built-in at
```
/docs
```
(Swagger UI) and
```
/redoc
```
. Ensure Pydantic models are used for request/response types so schemas are auto-generated.
Add interactive docs UI — serve Swagger UI at a
```
/docs
```
route, or use Scalar/Redoc for a modern alternative:
bash
```
npm install @scalar/express-api-reference
```
Define schemas — create Zod schemas (or JSON Schema) for request bodies and responses, then reference them in the OpenAPI spec. For TypeScript projects, use
```
zod-to-openapi
```
to generate schemas from existing Zod validators.
Add authentication documentation — document the auth scheme (Bearer token, API key, OAuth2) in the OpenAPI
```
securitySchemes
```
section.

检测API框架 — 检查是否使用Express、Fastify、Next.js API路由、Hono、Django REST Framework、FastAPI等。

针对Node.js/Express — 安装

swagger-jsdoc

和

swagger-ui-express

：

bash

npm install swagger-jsdoc swagger-ui-express
npm install -D @types/swagger-jsdoc @types/swagger-ui-express

从路由处理器上的JSDoc注释生成OpenAPI规范：

/**
 * @openapi
 * /api/users:
 *   get:
 *     summary: List all users
 *     responses:
 *       200:
 *         description: A list of users
 */

针对Next.js API路由 — 手动创建
```
openapi.json
```
文件，或使用
```
next-swagger-doc
```
从路由处理器生成。在
```
/api/docs
```
路径提供规范。
针对FastAPI（Python） — 文档内置在
```
/docs
```
（Swagger UI）和
```
/redoc
```
路径。确保使用Pydantic模型定义请求/响应类型，以便自动生成模式。
添加交互式文档UI — 在
```
/docs
```
路径提供Swagger UI，或使用Scalar/Redoc作为现代替代方案：
bash
```
npm install @scalar/express-api-reference
```
定义模式 — 为请求体和响应创建Zod模式（或JSON Schema），然后在OpenAPI规范中引用它们。对于TypeScript项目，使用
```
zod-to-openapi
```
从现有Zod验证器生成模式。
添加认证文档 — 在OpenAPI的
```
securitySchemes
```
部分记录认证方案（Bearer令牌、API密钥、OAuth2）。

Keep the spec in sync with the actual API — generate from code when possible rather than maintaining a separate YAML file.
Add example values to schemas for better developer experience.
Version the API docs alongside the code.