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/)。 |