123 lines
2.5 KiB
Markdown
123 lines
2.5 KiB
Markdown
|
# API文档生成与Apifox同步指南
|
|||
|
|
|
|||
|
|
本项目已集成Swagger用于API文档生成，并提供了与Apifox同步的工具脚本。
|
|||
|
|
|
|||
|
|
## 1. 查看API文档
|
|||
|
|
|
|||
|
|
启动服务器后，可以通过以下URL访问Swagger UI界面查看API文档：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
http://localhost:3000/api-docs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 2. 手动导出并导入Apifox
|
|||
|
|
|
|||
|
|
### 2.1 导出Swagger文档
|
|||
|
|
|
|||
|
|
运行以下命令导出Swagger文档：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
node export-swagger.js
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
这将在`api-docs`目录下生成`swagger.json`文件。
|
|||
|
|
|
|||
|
|
### 2.2 手动导入Apifox
|
|||
|
|
|
|||
|
|
1. 打开Apifox应用
|
|||
|
|
2. 选择您的项目
|
|||
|
|
3. 点击"导入"按钮
|
|||
|
|
4. 选择"导入OpenAPI(Swagger)"
|
|||
|
|
5. 选择刚才导出的swagger.json文件
|
|||
|
|
6. 按照Apifox的导入向导完成导入
|
|||
|
|
|
|||
|
|
## 3. 自动同步到Apifox
|
|||
|
|
|
|||
|
|
### 3.1 安装Apifox CLI
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npm install -g apifox-cli
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 登录Apifox CLI
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
apifox-cli login
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 配置项目ID
|
|||
|
|
|
|||
|
|
编辑`apifox-sync.js`文件，将`YOUR_APIFOX_PROJECT_ID`替换为您的Apifox项目ID。
|
|||
|
|
|
|||
|
|
> 获取项目ID：在Apifox网页版中打开项目，URL中包含项目ID
|
|||
|
|
|
|||
|
|
### 3.4 运行同步脚本
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
node apifox-sync.js
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 为API添加Swagger注释
|
|||
|
|
|
|||
|
|
为了使API文档保持最新，在添加新的API接口时，请按照以下格式添加Swagger注释：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
/**
|
|||
|
|
* @swagger
|
|||
|
|
* /api/resource:
|
|||
|
|
* get:
|
|||
|
|
* summary: 接口描述
|
|||
|
|
* tags: [资源分类]
|
|||
|
|
* parameters:
|
|||
|
|
* - name: param
|
|||
|
|
* in: query
|
|||
|
|
* description: 参数描述
|
|||
|
|
* required: true
|
|||
|
|
* schema:
|
|||
|
|
* type: string
|
|||
|
|
* responses:
|
|||
|
|
* 200:
|
|||
|
|
* description: 成功响应
|
|||
|
|
* content:
|
|||
|
|
* application/json:
|
|||
|
|
* schema:
|
|||
|
|
* type: object
|
|||
|
|
* properties:
|
|||
|
|
* success:
|
|||
|
|
* type: boolean
|
|||
|
|
* data:
|
|||
|
|
* type: object
|
|||
|
|
*/
|
|||
|
|
router.get('/resource', (req, res) => {
|
|||
|
|
// 实现代码
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 5. 定义数据模型
|
|||
|
|
|
|||
|
|
在路由文件顶部定义数据模型，例如：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
/**
|
|||
|
|
* @swagger
|
|||
|
|
* components:
|
|||
|
|
* schemas:
|
|||
|
|
* ModelName:
|
|||
|
|
* type: object
|
|||
|
|
* properties:
|
|||
|
|
* id:
|
|||
|
|
* type: integer
|
|||
|
|
* name:
|
|||
|
|
* type: string
|
|||
|
|
* required:
|
|||
|
|
* - name
|
|||
|
|
*/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 6. 自动化集成
|
|||
|
|
|
|||
|
|
可以将API文档生成和同步集成到CI/CD流程中，在每次部署前自动更新API文档。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
如有任何问题，请参考[Swagger官方文档](https://swagger.io/docs/)和[Apifox官方文档](https://www.apifox.cn/help/)。
|