82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
|
# API 接口文档使用说明
|
|||
|
|
|
|||
|
|
## 访问地址
|
|||
|
|
|
|||
|
|
启动应用后，可以通过以下地址访问 API 文档：
|
|||
|
|
|
|||
|
|
- **Swagger UI 界面**: http://localhost:8080/swagger-ui.html
|
|||
|
|
- **API 文档 JSON**: http://localhost:8080/v3/api-docs
|
|||
|
|
- **所有API分组**: http://localhost:8080/v3/api-docs/all
|
|||
|
|
|
|||
|
|
## 环境地址
|
|||
|
|
|
|||
|
|
根据部署环境，访问地址会有所不同：
|
|||
|
|
|
|||
|
|
- **本地开发**: http://localhost:8080/swagger-ui.html
|
|||
|
|
- **内网环境**: http://172.22.0.1:8080/swagger-ui.html
|
|||
|
|
- **生产环境**: https://vionow.com/swagger-ui.html
|
|||
|
|
|
|||
|
|
## API 分组
|
|||
|
|
|
|||
|
|
文档按功能模块分为以下分组：
|
|||
|
|
|
|||
|
|
1. **所有API (all)** - 查看所有接口
|
|||
|
|
2. **认证授权 (auth)** - 用户登录、注册、验证码等
|
|||
|
|
3. **用户作品 (user-works)** - 用户作品管理
|
|||
|
|
4. **视频生成 (video-generation)** - 文生视频、图生视频、分镜视频
|
|||
|
|
5. **支付管理 (payment)** - 订单、支付相关接口
|
|||
|
|
6. **会员管理 (member)** - 会员订阅、会员管理
|
|||
|
|
7. **积分系统 (points)** - 积分相关接口
|
|||
|
|
8. **任务管理 (tasks)** - 任务队列、任务状态
|
|||
|
|
9. **管理后台 (admin)** - 管理员功能、数据分析
|
|||
|
|
10. **系统设置 (settings)** - 系统配置、API密钥管理
|
|||
|
|
11. **公共接口 (public)** - 无需认证的公共接口
|
|||
|
|
|
|||
|
|
## 使用 JWT 认证
|
|||
|
|
|
|||
|
|
大部分接口需要 JWT 认证，使用步骤如下：
|
|||
|
|
|
|||
|
|
1. 在 Swagger UI 页面右上角点击 **"Authorize"** 按钮
|
|||
|
|
2. 在弹出框中输入 JWT Token（格式：`Bearer {token}` 或直接输入 token）
|
|||
|
|
3. 点击 **"Authorize"** 确认
|
|||
|
|
4. 之后所有请求都会自动携带认证信息
|
|||
|
|
|
|||
|
|
### 获取 Token
|
|||
|
|
|
|||
|
|
1. 调用 `/api/verification/email/send` 发送邮箱验证码
|
|||
|
|
2. 调用 `/api/auth/login/email` 使用邮箱和验证码登录
|
|||
|
|
3. 从响应中获取 `token` 字段
|
|||
|
|
4. 在 Swagger UI 中使用该 token 进行认证
|
|||
|
|
|
|||
|
|
## 功能特性
|
|||
|
|
|
|||
|
|
- ✅ 自动生成 API 文档
|
|||
|
|
- ✅ 在线测试接口
|
|||
|
|
- ✅ 支持 JWT 认证
|
|||
|
|
- ✅ API 分组管理
|
|||
|
|
- ✅ 请求/响应示例
|
|||
|
|
- ✅ 参数说明和验证规则
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **生产环境**: 建议在生产环境中限制 Swagger UI 的访问，或完全禁用
|
|||
|
|
2. **认证**: 大部分接口需要 JWT Token，请先登录获取 Token
|
|||
|
|
3. **权限**: 部分接口需要管理员权限，普通用户无法访问
|
|||
|
|
4. **跨域**: 如果遇到跨域问题，请检查 CORS 配置
|
|||
|
|
|
|||
|
|
## 禁用 Swagger UI（生产环境）
|
|||
|
|
|
|||
|
|
如果需要在生产环境禁用 Swagger UI，可以在 `application-prod.properties` 中添加：
|
|||
|
|
|
|||
|
|
```properties
|
|||
|
|
springdoc.swagger-ui.enabled=false
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
或者通过环境变量：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
export SPRINGDOC_SWAGGER_UI_ENABLED=false
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
|