接口文档

这篇解决什么

管理端和用户端的 REST 接口，要用注解生成 OpenAPI，再在浏览器里看、调试。读完能打开 http://127.0.0.1:48080/doc.html，给 Controller / VO 补 @Operation、@Schema，并在生产关掉文档页。

默认端口 48080，业务前缀 /admin-api、/app-api。类上的 @RequestMapping 不写前缀，由 WebProperties 拼上去。

从哪打开

单体 -P boot 时，文档和业务接口都在 yudao-server。

名称	说明	仓库路径
Knife4j	中文 UI，默认入口	http://127.0.0.1:48080/doc.html
OpenAPI JSON	全部分组	http://127.0.0.1:48080/v3/api-docs/all
Swagger UI	备用皮肤	http://127.0.0.1:48080/swagger-ui
PC 菜单	「基础设施 → API 接口」，iframe 嵌同一地址	ruoyi-office-vben/apps/web-antd/src/views/infra/swagger/index.vue
菜单数据	组件 infra/swagger/index，权限 infra:swagger:list	system_menu id 116
覆盖地址	参数 url.swagger 非空则改 iframe	infra_config

GET /*.html 免登录，所以浏览器可以直接开 /doc.html。/v3/api-docs/**、/webjars/**、/swagger-ui/** 在各模块 SecurityConfiguration 里 permitAll。

示意图：本机 48080/doc.html 打开后是分组 all，规范地址 /v3/api-docs/all。无头浏览器截中文会糊，按实际页面重画。

生产不要对外暴露

application-prod.yaml 已关：springdoc.api-docs.enabled=false、knife4j.enable=false、knife4j.production=true。共享环境若必须开文档，至少加 Knife4j Basic，不要把 /doc.html 裸挂公网。

在页面里调试

点左侧 @Tag 分组，再点一条接口。调试前勾上两个全局请求头。

名称	说明	仓库路径
tenant-id	租户编号，默认 1	YudaoSwaggerAutoConfiguration#buildTenantHeaderParameter
Authorization	认证 Token，默认 Bearer test1	同文件 #buildSecurityHeaderParameter

test1 不是随意字符串：yudao.security.mock-secret 默认 test，后面跟用户编号。Bearer test1 表示模拟用户 1。开关是 yudao.security.mock-enable，application-dev.yaml 为 true，application-prod.yaml 为 false。

示意图：登录接口 POST /admin-api/system/auth/login，头里带租户和 Token。

本地也可以先调登录，把返回的 accessToken 填进 Authorization: Bearer {token}，不必用 mock。

mock 只给本机

TokenAuthenticationFilter#mockLoginUser 在 mock-enable=false 时直接返回空。生产必须保持关闭，否则知道密钥规则就能冒充任意用户。

登录本身带 @PermitAll，不带头也能调。其它管理端接口缺 Token 会走统一未登录响应，见 异常处理。

注解怎么写

SpringDoc 读的是 OpenAPI 3 注解，不是 Java 注释。以认证为例：

@Tag(name = "管理后台 - 认证")
@RestController
@RequestMapping("/system/auth")
public class AuthController {

    @PostMapping("/login")
    @PermitAll
    @Operation(summary = "使用账号密码登录")
    public CommonResult<AuthLoginRespVO> login(@RequestBody @Valid AuthLoginReqVO reqVO) {
        return success(authService.login(reqVO));
    }
}

实际 URL 是 /admin-api/system/auth/login。路径：ruoyi-office/yudao-module-system/yudao-module-system-server/.../controller/admin/auth/AuthController.java。

名称	说明	仓库路径
@Tag	左侧分组名	Controller 类上
@Operation	接口标题；访问日志也会读 summary	方法上
@Parameter	Query / Path 参数说明	例如 refreshToken
@Schema	VO 字段说明、必填、示例	例如 AuthLoginReqVO
@Valid	校验失败进全局异常，文档里也能看到约束	与 VO 一起用

VO 不要用 DO 当入参。字段说明挂在 @Schema 上，校验挂在 @NotEmpty 等注解上：

@Schema(description = "管理后台 - 账号密码登录 Request VO")
public class AuthLoginReqVO extends CaptchaVerificationReqVO {

    @Schema(description = "账号", requiredMode = Schema.RequiredMode.REQUIRED)
    @NotEmpty(message = "登录账号不能为空")
    private String username;
}

operationId 由框架改成「类名前缀 + 方法名」，例如 Auth_login，避免 Admin / App 两个 UserController 撞名。

返回必须是 CommonResult<T>，文档里的响应结构才和前端约定一致。不要指望自动包装。

封装与配置

名称	说明	仓库路径
SpringDoc	2.8.17，扫注解出 OpenAPI 3	yudao-dependencies
Knife4j	4.5.0，UI 与网关聚合	同上
自动配置	注册 OpenAPI、分组、全局头	yudao-framework/yudao-spring-boot-starter-web/.../swagger/config/YudaoSwaggerAutoConfiguration.java
属性	标题、描述、版本	yudao.swagger.* → SwaggerProperties
兼容补丁	Boot 3.4+ 的 Knife4j 扩展	Knife4jOpenApiCustomizer

yudao-server 默认打开：

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui
  default-flat-param-object: true

knife4j:
  enable: true
  setting:
    language: zh_cn

allGroupedOpenApi 匹配 /admin-api/** 与 /app-api/**。个别模块再调 YudaoSwaggerAutoConfiguration.buildGroupedOpenApi("wms") 之类，按路径切组。

文档页免登录，不等于业务接口免登录。调试时仍要带 tenant-id 和 Authorization。

微服务怎么聚合

-P cloud 时各 *-server 自己出 /v3/api-docs。网关端口仍是 48080，用 Knife4j Gateway 按模块拉文档。

名称	说明	仓库路径
网关聚合	knife4j.gateway.enabled=true	ruoyi-office/yudao-gateway/src/main/resources/application.yaml
转发	/admin-api/{module}/v3/api-docs 改写到服务根路径 /v3/api-docs	同文件各路由 RewritePath
示例	system 文档	/admin-api/system/v3/api-docs

本地日常二开走单体即可。切微服务后，浏览器仍打开网关的 /doc.html，不要去记每个服务自己的端口。

导入到其它调试工具

把 http://127.0.0.1:48080/v3/api-docs/all 当 OpenAPI 源导入即可。环境地址填 http://127.0.0.1:48080，调试时同样带 tenant-id 和 Authorization。

GET 分页的时间数组

createTime 这类 LocalDateTime[] 查询参数，导入后若带上 [] 会绑失败。去掉方括号再发。日期格式见项目日期时间约定：PageReqVO 用 @DateTimeFormat，不要和 JSON 的 @JsonFormat 混用。

需要关文档时，把 springdoc.api-docs.enabled 与 knife4j.enable 设为 false。生产配置已经这样写，不要在 prod 再打开。

配置与操作

开发本地打开 knife4j.enable，管理端 基础设施 → API 接口 iframe 默认 {VITE_BASE_URL}/doc.html，可被 infra_config 的 url.swagger 覆盖。改 yaml 要重启。

生产保持关闭。没有「接口文档」业务表可改。开启见 基建功能设计。

相关篇

• 基建功能设计
• 异常处理
• VO 对象转换与数据翻译
• 项目结构