OARS Docs

Appearance

接口 ​

适用对象 ​

给接口设计、前后端联调、AI 生成 API 调整和排错使用。

入口 ​

  • 服务前缀：/oars
  • 登录：POST /oars/app/auth/login
  • 刷新：POST /oars/app/auth/refresh（Body：{ "refreshToken": "..." }）
  • 登出：POST /oars/app/auth/logout（Header 须带 Bearer，Token 才入黑名单）
  • 当前用户：GET /oars/app/auth/user/info
  • Swagger UI：http://localhost:8080/oars/swagger-ui.html
  • OpenAPI：/oars/v3/api-docs/**
  • 配置与联调细节：oars-java/SWAGGER-GUIDE.md

Swagger 联调（摘要） ​

  • UI 与文档 JSON 免登录；在 UI 里 Execute 调业务接口仍需 Authorization: Bearer <accessToken>。
  • 建议：先 POST /app/auth/login 取 token，再在 Try it out 请求头填入 Bearer。
  • 顶部分组由 SwaggerConfig 定义（默认 全部接口）；模块内再按 Controller @Tag 归类。
  • 生产环境 未默认关闭 Swagger，部署见 L2 §生产环境。

关键约定 ​

  • 通用响应以 code: 200 表示成功，前端 requestClient 默认返回 data。
  • 需要认证的请求使用 Authorization: Bearer <accessToken>。
  • 401 触发前端刷新 Token；刷新失败后进入重新登录流程。
  • 开发 AI 生成器接口挂在 /app/dev/module-generator，并需要 ai:module-generator 权限。
  • 触发限流返回 HTTP 429，响应 message 为“请求过于频繁，请稍后再试”。

实现位置 ​

  • 前端请求封装：oars-web/apps/web-antd/src/api/request.ts
  • 生成器 API 客户端：oars-web/apps/web-antd/src/api/dev/module-generator.ts
  • 生成器 Controller：oars-java/oars-app/src/main/java/com/oars/app/controller/app/DevModuleGeneratorController.java
  • 认证 Controller：oars-java/oars-app/src/main/java/com/oars/app/controller/app/AuthController.java
  • 限流配置：oars-java/oars-app/src/main/java/com/oars/app/config/RateLimitInterceptor.java

待确认事项 ​

  • 非 200 业务错误码是否需要统一枚举。
  • 分页请求和响应字段需要按现有 Controller 再抽一版通用约定。

L2 详细说明（monorepo） ​

主题文档
Swagger 访问与配置oars-java/SWAGGER-GUIDE.md
JWT 认证oars-java/AUTH-GUIDE.md
限流oars-java/RATE-LIMIT-CONFIG.md