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