168 lines
3.8 KiB
Markdown
168 lines
3.8 KiB
Markdown
|
# 文档脚本说明
|
|||
|
|
|
|||
|
|
## API 文档自动生成脚本
|
|||
|
|
|
|||
|
|
### 功能说明
|
|||
|
|
|
|||
|
|
`generate-api-docs.js` 脚本用于从后端的 Swagger API 自动生成前端文档。
|
|||
|
|
|
|||
|
|
### 使用方法
|
|||
|
|
|
|||
|
|
#### 1. 安装依赖
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd admin/docs
|
|||
|
|
npm install
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2. 运行自动生成脚本
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 使用默认配置（http://localhost:3000）
|
|||
|
|
npm run generate-api
|
|||
|
|
|
|||
|
|
# 指定后端服务地址
|
|||
|
|
BACKEND_URL=http://your-backend-url npm run generate-api
|
|||
|
|
|
|||
|
|
# 开发环境快捷命令
|
|||
|
|
npm run generate-api:dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3. 查看生成结果
|
|||
|
|
|
|||
|
|
生成完成后，会在以下目录生成文档：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
admin/docs/src/wwjcloud/openapi/api/
|
|||
|
|
├── api/ # 前台 API (对应后端 /api/)
|
|||
|
|
│ ├── index.md # 前台 API 概览
|
|||
|
|
│ ├── member.md # 会员管理 API (自动生成)
|
|||
|
|
│ ├── auth.md # 认证 API (自动生成)
|
|||
|
|
│ └── ... # 其他模块 API
|
|||
|
|
└── adminapi/ # 后台 API (对应后端 /adminapi/)
|
|||
|
|
├── index.md # 后台 API 概览
|
|||
|
|
├── member.md # 会员管理 API (自动生成)
|
|||
|
|
├── admin.md # 管理员 API (自动生成)
|
|||
|
|
└── ... # 其他模块 API
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 配置说明
|
|||
|
|
|
|||
|
|
#### 环境变量
|
|||
|
|
|
|||
|
|
- `BACKEND_URL`: 后端服务地址，默认为 `http://localhost:3000`
|
|||
|
|
|
|||
|
|
#### API 分组配置
|
|||
|
|
|
|||
|
|
脚本会自动处理以下 API 分组：
|
|||
|
|
|
|||
|
|
- **前台 API**: `/api-json` (对应后端 `/api/` 路径)
|
|||
|
|
- **后台 API**: `/adminapi-json` (对应后端 `/adminapi/` 路径)
|
|||
|
|
|
|||
|
|
### 自动生成内容
|
|||
|
|
|
|||
|
|
生成的文档包含：
|
|||
|
|
|
|||
|
|
- **API 接口列表**: 按模块自动分组
|
|||
|
|
- **请求参数说明**: 自动解析 Swagger 参数定义
|
|||
|
|
- **响应示例**: 统一的响应格式
|
|||
|
|
- **接口描述**: 从 Swagger 自动提取
|
|||
|
|
- **在线测试链接**: 指向后端 Swagger UI
|
|||
|
|
|
|||
|
|
### 目录结构对齐
|
|||
|
|
|
|||
|
|
前端文档目录结构与后端保持一致：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
后端路径 前端文档路径
|
|||
|
|
/api/ → /api/
|
|||
|
|
/adminapi/ → /adminapi/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 注意事项
|
|||
|
|
|
|||
|
|
1. **后端服务必须运行**: 确保后端服务已启动并可访问
|
|||
|
|
2. **Swagger 配置**: 确保后端已正确配置 Swagger 文档
|
|||
|
|
3. **网络连接**: 确保能够访问后端服务地址
|
|||
|
|
4. **权限问题**: 某些 API 可能需要认证才能访问
|
|||
|
|
|
|||
|
|
### 故障排除
|
|||
|
|
|
|||
|
|
#### 1. 连接失败
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 检查后端服务是否运行
|
|||
|
|
curl http://localhost:3000/api-json
|
|||
|
|
|
|||
|
|
# 检查网络连接
|
|||
|
|
ping localhost
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 2. 权限问题
|
|||
|
|
|
|||
|
|
如果 API 需要认证，可以在脚本中添加认证头：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// 在 generate-api-docs.js 中修改
|
|||
|
|
const response = await axios.get(url, {
|
|||
|
|
headers: {
|
|||
|
|
'Authorization': 'Bearer your-token'
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3. 文档生成失败
|
|||
|
|
|
|||
|
|
检查输出目录权限：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 确保目录存在且有写权限
|
|||
|
|
ls -la admin/docs/src/wwjcloud/openapi/api/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 自定义配置
|
|||
|
|
|
|||
|
|
如需自定义配置，可以修改 `generate-api-docs.js` 中的 `config` 对象：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
const config = {
|
|||
|
|
// 修改后端服务地址
|
|||
|
|
backendUrl: process.env.BACKEND_URL || 'http://localhost:3000',
|
|||
|
|
|
|||
|
|
// 修改输出目录
|
|||
|
|
docsDir: path.join(__dirname, '../src/wwjcloud/openapi/api'),
|
|||
|
|
|
|||
|
|
// 添加新的 API 分组
|
|||
|
|
apiGroups: {
|
|||
|
|
// ... 现有配置
|
|||
|
|
custom: {
|
|||
|
|
name: '自定义 API',
|
|||
|
|
swaggerPath: '/custom-json',
|
|||
|
|
outputDir: 'custom',
|
|||
|
|
prefix: '/custom'
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 集成到 CI/CD
|
|||
|
|
|
|||
|
|
可以将自动生成脚本集成到 CI/CD 流程中：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# GitHub Actions 示例
|
|||
|
|
- name: Generate API Docs
|
|||
|
|
run: |
|
|||
|
|
cd admin/docs
|
|||
|
|
npm install
|
|||
|
|
npm run generate-api
|
|||
|
|
env:
|
|||
|
|
BACKEND_URL: ${{ secrets.BACKEND_URL }}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 相关文件
|
|||
|
|
|
|||
|
|
- `generate-api-docs.js`: 主自动生成脚本
|
|||
|
|
- `package.json`: 脚本命令配置
|
|||
|
|
- `src/wwjcloud/openapi/api/`: 生成的文档目录
|
|||
|
|
- `.vitepress/config/zh.mts`: 侧边栏配置
|