# 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
```