81 lines
2.1 KiB
Markdown
81 lines
2.1 KiB
Markdown
# API 文档结构说明
|
|
|
|
本项目已将 Swagger API 文档从路由文件中分离出来，采用模块化的文档管理方式。
|
|
|
|
## 文件夹结构
|
|
|
|
```
|
|
docs/
|
|
├── README.md # 本说明文件
|
|
├── schemas/ # 数据模型定义
|
|
│ ├── product.js # 商品相关数据模型
|
|
│ ├── order.js # 订单相关数据模型
|
|
│ ├── user.js # 用户相关数据模型
|
|
│ ├── cart.js # 购物车相关数据模型
|
|
│ └── announcement.js # 通知公告相关数据模型
|
|
└── apis/ # API 接口定义
|
|
├── products.js # 商品相关 API
|
|
├── orders.js # 订单相关 API
|
|
└── announcements.js # 通知公告相关 API
|
|
```
|
|
|
|
## 优势
|
|
|
|
1. **模块化管理**: 按功能模块分离文档，便于维护和查找
|
|
2. **代码分离**: 路由文件专注于业务逻辑，文档定义独立管理
|
|
3. **复用性**: Schema 定义可以在多个 API 中复用
|
|
4. **可维护性**: 文档修改不会影响业务代码，降低出错风险
|
|
|
|
## 使用方法
|
|
|
|
### 添加新的 Schema
|
|
|
|
在 `schemas/` 文件夹中创建新的 `.js` 文件，使用 `@swagger` 注释定义数据模型：
|
|
|
|
```javascript
|
|
/**
|
|
* @swagger
|
|
* components:
|
|
* schemas:
|
|
* YourModel:
|
|
* type: object
|
|
* properties:
|
|
* id:
|
|
* type: integer
|
|
* description: ID
|
|
*/
|
|
```
|
|
|
|
### 添加新的 API 文档
|
|
|
|
在 `apis/` 文件夹中创建新的 `.js` 文件，使用 `@swagger` 注释定义 API 接口：
|
|
|
|
```javascript
|
|
/**
|
|
* @swagger
|
|
* tags:
|
|
* name: YourModule
|
|
* description: 模块描述
|
|
*/
|
|
|
|
/**
|
|
* @swagger
|
|
* /your-endpoint:
|
|
* get:
|
|
* summary: 接口描述
|
|
* tags: [YourModule]
|
|
* responses:
|
|
* 200:
|
|
* description: 成功响应
|
|
*/
|
|
```
|
|
|
|
## 配置
|
|
|
|
Swagger 配置文件 `swagger.js` 已更新扫描路径：
|
|
|
|
```javascript
|
|
apis: ['./docs/schemas/*.js', './docs/apis/*.js', './routes/*.js', './admin/routes/*.js']
|
|
```
|
|
|
|
这样既保持了对现有路由文件中文档的兼容性，又支持新的模块化文档结构。 |