常见场景

让某个接口的文档不被 Result 包裹

加 @RawResponse，文档与运行时一并跳过包装：

@GetMapping("/stream")
@RawResponse
public ResponseEntity<byte[]> downloadFile() {
    byte[] bytes = loadFile();
    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .body(bytes);
}

详细注解用法见 guide/core/annotations。

生产环境关闭 Swagger 与 Knife4j

通过 Spring Profile 配合 application-prod.yml：

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

knife4j:
  enable: false
  production: true

knife4j.production=true 会让 Knife4j 拒绝任何未授权访问，相当于双保险。

部署时启用 Profile

通过 --spring.profiles.active=prod 或环境变量 SPRING_PROFILES_ACTIVE=prod 切换。

把接口按业务域拆成多个文档分组

利用 springdoc 的 group-configs，每个分组一个独立的 Swagger 文档：

springdoc:
  group-configs:
    - group: 用户中心
      paths-to-match: /v1/user/**, /v2/user/**
      packages-to-scan: com.demo.app.user.controller
    - group: 订单中心
      paths-to-match: /v1/order/**
      packages-to-scan: com.demo.app.order.controller

Knife4j UI 顶部会出现「用户中心 / 订单中心」切换菜单。

自定义 contact / license / 服务器列表

参考 配置说明 · 覆盖默认 OpenAPI Bean 的示例代码。

给某接口指定自定义示例

springdoc 支持 @io.swagger.v3.oas.annotations.media.ExampleObject 注解：

@PostMapping
@io.swagger.v3.oas.annotations.responses.ApiResponse(
        responseCode = "200",
        content = @io.swagger.v3.oas.annotations.media.Content(
                examples = @io.swagger.v3.oas.annotations.media.ExampleObject(
                        value = "{\"success\":true,\"code\":200,\"message\":\"操作成功\",\"data\":{\"id\":42,\"name\":\"张三\"}}"
                )
        )
)
public UserDTO create(@Valid @RequestBody UserDTO dto) {
    return userService.create(dto);
}

GlobalResultOperationCustomizer 在 Ordered.LOWEST_PRECEDENCE 阶段才介入，会保留 springdoc 已经设置的 examples，不会把它清掉。

让某个接口的文档强制不出现在 Swagger

springdoc 提供 @io.swagger.v3.oas.annotations.Hidden：

@Hidden
@GetMapping("/internal/dump")
public Map<String, Object> internalDump() {
    return Map.of("cache", cacheState());
}

接口仍然可调用，但不会出现在 Swagger UI 与 OpenAPI JSON 里。