【最后的结论】

要想使用Spring Boot接口文档功能，有以下两种方式：

方式1：

<!-- OpenAPI3 + Swagger UI for Spring MVC -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>3.0.3</version>
</dependency>

方式2（推荐）：

<!-- Knife4j OpenAPI3 for Spring Boot 3.x -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

 

---

 

下面这几个词，经常被混在一起说。其实它们不是同一层级的东西，可以先用一句话区分：

OpenAPI3 是接口文档规范；Swagger3 是围绕 OpenAPI3 的一套工具/注解生态；springdoc-openapi 是 Spring Boot 里自动生成 OpenAPI3 文档的 Java 库；Swagger UI 是展示和调试接口文档的前端页面；Knife4j 是在 Swagger/OpenAPI 基础上做了增强的接口文档 UI 和聚合方案。

一、先看整体关系图

你的 Spring Boot Controller
        │
        │ 读取 @GetMapping / @PostMapping / 参数 / 返回值 / OpenAPI 注解
        ▼
springdoc-openapi
        │
        │ 生成 OpenAPI3 JSON/YAML
        │  例如：/v3/api-docs
        ▼
OpenAPI3 规范文档
        │
        ├──────────────► Swagger UI 展示、调试
        │
        └──────────────► Knife4j 展示、调试、增强、聚合

也就是说：

OpenAPI3 = 标准
Swagger3 = 工具生态/注解生态
springdoc-openapi = Spring Boot 自动生成 OpenAPI3 的后端库
Swagger UI = 官方风格的接口文档页面
Knife4j = 国内常用的增强版接口文档页面

OpenAPI 官方定义里，OAS 是一种语言无关的 HTTP API 描述规范，让人和机器都能理解服务能力，而不需要看源码或抓包。(OpenAPI Initiative Publications) Swagger 官方也说明，OpenAPI 以前叫 Swagger Specification，用来描述 REST API 的接口路径、请求参数、响应、认证方式等。(Swagger)

二、OpenAPI3 是什么？

1. 它是“接口文档标准”

OpenAPI3 不是一个 Java 库，也不是一个页面，而是一套描述 REST API 的标准格式。

比如你有一个接口：

GET /users/{id}

OpenAPI3 文档会描述：

openapi: 3.0.3
info:
  title: 用户中心接口
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: 根据用户ID查询用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 查询成功

这份 YAML/JSON 就是 OpenAPI3 格式的接口说明书。

2. 它解决什么问题？

没有 OpenAPI3 之前，接口文档可能是 Word、Excel、Markdown、Postman、Wiki，各写各的，很难统一。

OpenAPI3 解决的是：

问题	OpenAPI3 的作用
前后端接口对不齐	用统一结构描述接口
文档靠人工维护，容易过期	可以从代码自动生成
测试人员不知道参数怎么传	明确请求参数、响应结构
第三方系统对接成本高	给对方一份标准 JSON/YAML
想生成 SDK	可以基于 OpenAPI 生成客户端代码
想导入 Apifox/Postman	多数接口工具支持导入 OpenAPI

3. OpenAPI3 不是 Swagger UI

很多人会说：

“打开 Swagger 看接口。”

严格来说，这句话通常指的是打开 Swagger UI 页面，不是 OpenAPI 本身。

OpenAPI3 是底层文档标准，例如：

/v3/api-docs

Swagger UI 或 Knife4j 是把这份 JSON 渲染成网页，例如：

/swagger-ui/index.html
/doc.html

三、Swagger3 是什么？

1. Swagger 和 OpenAPI 的历史关系

以前大家说 Swagger，既可能指规范，也可能指工具。

后来 Swagger Specification 被标准化为 OpenAPI Specification，所以现在更准确的说法是：

Swagger Specification 2.0 以前常叫 Swagger
OpenAPI 3.x 是后来的标准规范
Swagger 现在更多指工具生态

Swagger 官方文档也明确提到，OpenAPI Specification 以前叫 Swagger Specification。(Swagger)

2. Swagger3 通常指什么？

在 Java/Spring Boot 语境下，“Swagger3”一般有几种含义：

含义一：使用 OpenAPI3 规范

也就是不再使用老的 Swagger2 规范，而是使用 OpenAPI 3.x。

含义二：使用 Swagger/OpenAPI 3 注解

比如这些注解来自：

io.swagger.v3.oas.annotations.*

常见注解：

@Operation
@Parameter
@Schema
@ApiResponse
@Tag

示例：

@Tag(name = "用户管理")
@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "根据ID查询用户")
    @GetMapping("/{id}")
    public UserDTO getById(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id) {
        return new UserDTO();
    }
}

含义三：Swagger UI 3.x

有些人说 Swagger3，其实说的是 Swagger UI 的新版本页面。

3. 容易混淆点

说法	严格含义	常见误用
Swagger	工具生态、品牌、历史规范名	被泛指为接口文档
Swagger2	老规范或 Springfox 时代的实现	很多老项目还在用
Swagger3	通常指 OpenAPI3 生态	不是一个单独标准
OpenAPI3	正式接口规范	经常被叫成 Swagger3

四、springdoc-openapi 是什么？

1. 它是 Spring Boot 项目里的“文档生成器”

springdoc-openapi 是一个 Java 库，用于在 Spring Boot 项目里自动生成 OpenAPI3 文档。官方介绍中，springdoc-openapi 会检查 Spring Boot 项目来自动生成 API 文档。(GitHub)

你写了 Controller：

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public UserDTO getById(@PathVariable Long id) {
        return new UserDTO();
    }
}

springdoc-openapi 会自动分析：

@GetMapping("/{id}")      -> GET /users/{id}
@PathVariable Long id    -> path 参数 id
UserDTO                  -> 响应模型

然后生成：

/v3/api-docs

这个地址返回的就是 OpenAPI3 JSON。

2. Spring Boot 3 常用依赖

Spring Boot 3 项目通常使用：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>当前稳定版本</version>
</dependency>

引入后通常可以访问：

/v3/api-docs
/swagger-ui/index.html

其中：

地址	作用
/v3/api-docs	OpenAPI3 JSON 原始文档
/swagger-ui/index.html	Swagger UI 页面

springdoc 官方也说明，它内置支持 Swagger UI，Swagger UI 会基于 OpenAPI Specification 自动生成可视化文档页面。(OpenAPI 3 Library for spring-boot)

3. springdoc-openapi 和 Swagger UI 的关系

很多人引入这个依赖：

springdoc-openapi-starter-webmvc-ui

然后看到页面：

/swagger-ui/index.html

就以为 springdoc-openapi 等于 Swagger UI。

其实不是。

springdoc-openapi = 后端扫描代码，生成 OpenAPI JSON
Swagger UI = 前端展示这个 JSON

这个 starter 只是帮你把两者一起集成了。

五、Swagger UI 是什么？

1. 它是接口文档展示页面

Swagger UI 是一个前端页面，用 HTML、CSS、JavaScript 把 OpenAPI JSON/YAML 渲染成可阅读、可调试的接口文档。Swagger 官方说明，Swagger UI 可以让开发团队可视化并交互调用 API 资源。(Swagger) GitHub 项目也说明 Swagger UI 是一组 HTML、JavaScript、CSS 资源，可以根据 Swagger/OpenAPI 文档动态生成文档页面。(GitHub)

页面大概长这样：

用户管理
  GET /users/{id}
    Parameters:
      id
    Responses:
      200
    Try it out

2. Swagger UI 做什么？

它主要负责：

功能	说明
展示接口列表	按 Controller/Tag 展示接口
展示参数	path、query、body、header 参数
展示响应结构	DTO、字段类型、示例
在线调试接口	Try it out
展示认证配置	Bearer Token、Basic Auth 等
读取 OpenAPI 文档	读取 /v3/api-docs 或其他 OpenAPI 地址

3. Swagger UI 不负责什么？

Swagger UI 不负责扫描 Java 代码，也不负责生成 /v3/api-docs。

它只是展示已有的 OpenAPI 文档。

Swagger UI 需要一个 OpenAPI JSON/YAML 输入

这个输入可以来自：

springdoc-openapi
Springfox
手写 openapi.yaml
网关聚合出来的文档
其他语言框架生成的文档

六、Knife4j 是什么？

1. 它是 Swagger/OpenAPI 的增强方案

Knife4j 官方介绍是：集 Swagger2 和 OpenAPI3 为一体的增强解决方案，帮助开发者快速聚合使用 OpenAPI 规范。(Knife4j)

你可以简单理解为：

Knife4j ≈ 增强版 Swagger UI + 一些后端 starter + 网关聚合能力

2. Knife4j 比 Swagger UI 增强在哪里？

Knife4j 常见增强点包括：

能力	Swagger UI	Knife4j
基础接口展示	支持	支持
在线调试	支持	支持
中文体验	一般	更友好
接口分组	支持	更方便
文档增强说明	一般	更丰富
接口排序	基础	更方便
导出文档	通常较弱	支持增强
动态参数调试	基础	更友好
网关聚合接口文档	需要额外方案	官方提供相关能力
国内团队使用体验	一般	更符合国内习惯

Knife4j 官方文档也列出基础 UI 组件、自定义文档、动态参数调试、I18n、接口排序、导出，以及基于 Springdoc-openapi + OAS3 的自动注入 starter 和网关聚合 OpenAPI 接口文档方案。(Knife4j)

3. Knife4j 页面地址

集成 Knife4j 后，常见访问地址是：

/doc.html

而 Swagger UI 通常是：

/swagger-ui/index.html

4. Spring Boot 3 集成 Knife4j 要注意

Knife4j 官方快速开始文档提示：Spring Boot 3 只支持 OpenAPI3 规范，Knife4j 的 starter 已经引用 springdoc-openapi 的 jar，需要注意避免 jar 包冲突，并且 JDK 版本要求不低于 17。(Knife4j)

也就是说，在 Spring Boot 3 项目里，如果你用了 Knife4j 的 OpenAPI3 starter，通常不要再重复乱引 springdoc 的其他版本，否则容易依赖冲突。

七、它们之间的核心区别

1. 分层对比

名称	类型	主要作用	是否生成接口文档	是否展示页面	常见地址
OpenAPI3	规范/标准	定义接口文档格式	否	否	无
Swagger3	工具生态/注解生态	围绕 OpenAPI3 的工具、注解、UI	视具体工具而定	视具体工具而定	不固定
springdoc-openapi	Java 后端库	扫描 Spring Boot 代码生成 OpenAPI3	是	starter-ui 可带 Swagger UI	/v3/api-docs
Swagger UI	前端页面	展示 OpenAPI 文档并调试	否	是	/swagger-ui/index.html
Knife4j	增强 UI/增强方案	展示、调试、增强、聚合 OpenAPI 文档	starter 可集成生成能力	是	/doc.html

2. 一句话版本

名称	一句话理解
OpenAPI3	接口文档的“标准格式”
Swagger3	基于 OpenAPI3 的“工具和注解生态”
springdoc-openapi	Spring Boot 里“自动生成 OpenAPI3 文档”的库
Swagger UI	官方风格的“接口文档网页”
Knife4j	更适合国内项目的“增强版接口文档网页/聚合方案”

八、场景举例说明

场景一：普通 Spring Boot 单体项目

需求

公司有一个用户管理系统，需要让前端知道有哪些接口。

比如：

GET /users/{id}
POST /users
PUT /users/{id}
DELETE /users/{id}

推荐方案

使用：

springdoc-openapi-starter-webmvc-ui

Maven坐标

<!-- OpenAPI3 + Swagger UI for Spring MVC -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>3.0.3</version>
</dependency>

结果

后端自动生成：

/v3/api-docs

前端访问：

/swagger-ui/index.html

适合情况

情况	是否适合
项目简单	很适合
接口数量不多	很适合
团队能接受 Swagger UI	很适合
不需要复杂导出/增强功能	很适合

场景二：国内企业后台系统，希望文档更好看、更好用

需求

公司内部有很多接口，测试、前端、后端都会看接口文档，希望页面更直观，支持接口排序、分组、导出、增强说明。

推荐方案

使用：

Knife4j + OpenAPI3 + springdoc-openapi

或者直接引入 Knife4j 的 OpenAPI3 Spring Boot starter。

<!-- Knife4j OpenAPI3 for Spring Boot 3.x -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

结果

访问：

/doc.html

页面通常比 Swagger UI 更适合中文团队使用。

适合情况

情况	是否适合
国内企业项目	很适合
接口比较多	很适合
测试人员频繁调接口	很适合
需要导出接口文档	适合
需要接口聚合	适合

场景三：微服务架构，需要统一查看多个服务接口

需求

有多个服务：

用户服务 user-service
订单服务 order-service
仓库服务 warehouse-service
财务服务 finance-service

每个服务都有自己的 OpenAPI 文档：

user-service/v3/api-docs
order-service/v3/api-docs
warehouse-service/v3/api-docs
finance-service/v3/api-docs

希望在一个统一入口查看所有接口。

可选方案

网关 + Knife4j 聚合

或者：

网关 + Swagger UI 配置多个 urls

更推荐

如果是国内团队，并且希望聚合体验更强，Knife4j 更常见。

整体结构

浏览器
  │
  ▼
API 网关 / 文档网关
  │
  ├── 用户服务 /v3/api-docs
  ├── 订单服务 /v3/api-docs
  ├── 仓库服务 /v3/api-docs
  └── 财务服务 /v3/api-docs

场景四：给第三方系统对接

需求

你们公司开放接口给外部客户，比如：

创建订单
查询物流
取消订单
查询库存

第三方客户希望拿到标准文档，甚至导入他们自己的接口管理工具。

推荐输出

直接提供：

openapi.json

或：

openapi.yaml

这里谁最重要？

这个场景里最重要的是：

OpenAPI3

因为对方不一定用你的 Swagger UI 或 Knife4j 页面，但他们可以导入 OpenAPI3 文件到：

Postman
Apifox
YApi
Apigee
Stoplight
OpenAPI Generator

场景五：前后端并行开发

需求

后端还没开发完，前端想先根据接口协议开发页面。

推荐方式

先设计 OpenAPI3 文档：

paths:
  /orders:
    post:
      summary: 创建订单

然后前端根据 OpenAPI 文档 mock 数据。

这个场景下的重点

OpenAPI3 是契约

后端和前端都围绕它开发。

这个叫：

API First

也就是先设计接口规范，再开发代码。

场景六：代码先行的普通后端开发

需求

大部分 Java 后端团队习惯先写 Controller，然后自动生成接口文档。

推荐方式

Code First

也就是：

Controller 代码
    ↓
springdoc-openapi 扫描
    ↓
OpenAPI3 JSON
    ↓
Swagger UI / Knife4j 展示

这也是 Spring Boot 项目最常见的方式。

九、Spring Boot 代码示例

1. Controller 示例

package com.example.demo.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@Tag(name = "用户管理", description = "用户查询、新增、修改、删除接口")
@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "根据用户ID查询用户")
    @GetMapping("/{id}")
    public UserDTO getById(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id) {
        return new UserDTO(id, "张三", "zhangsan@example.com");
    }

    @Operation(summary = "新增用户")
    @PostMapping
    public UserDTO create(@RequestBody UserCreateRequest request) {
        return new UserDTO(1L, request.getName(), request.getEmail());
    }
}

2. DTO 示例

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户信息")
public class UserDTO {

    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户名", example = "张三")
    private String name;

    @Schema(description = "邮箱", example = "zhangsan@example.com")
    private String email;

    public UserDTO(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    // getter/setter
}

3. 这些注解是谁的？

这些注解：

@Operation
@Parameter
@Schema
@Tag

来自：

io.swagger.v3.oas.annotations

它们属于 Swagger/OpenAPI 3 注解生态。

springdoc-openapi 会读取这些注解，然后生成 OpenAPI3 文档。

十、Spring Boot 依赖选择

方案一：只用 springdoc-openapi + Swagger UI

适合普通项目。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>当前稳定版本</version>
</dependency>

访问：

/v3/api-docs
/swagger-ui/index.html

方案二：用 Knife4j

适合希望增强 UI 的项目。

Spring Boot 3 通常使用 Knife4j OpenAPI3 Jakarta starter，具体版本建议以 Knife4j 官方文档为准，因为它会随 Spring Boot、Springdoc 版本变化。Knife4j 官方快速开始页给出的 Spring Boot 3 示例依赖是 knife4j-openapi3-jakarta-spring-boot-starter，并提示其已引用 springdoc-openapi，需要避免 jar 包冲突。(Knife4j)

访问：

/doc.html

十一、常见误区

误区一：OpenAPI3 等于 Swagger UI

错误。

OpenAPI3 是文档标准
Swagger UI 是展示页面

误区二：springdoc-openapi 等于 Swagger

不准确。

springdoc-openapi 是 Spring Boot 的 OpenAPI 文档生成库
Swagger 是更大的工具生态

误区三：用了 Knife4j 就不需要 OpenAPI3

错误。

Knife4j 也是基于 Swagger/OpenAPI 文档工作的。没有 OpenAPI3 JSON，Knife4j 页面也没有东西可展示。

误区四：Swagger UI 和 Knife4j 必须二选一

不一定。

一个项目理论上可以同时保留：

/swagger-ui/index.html
/doc.html

但实际项目里一般选一个，避免重复维护和依赖冲突。

误区五：接口文档页面可以直接暴露到公网

不建议。

生产环境要控制访问权限，尤其是：

/swagger-ui/index.html
/doc.html
/v3/api-docs

否则外部人员可能看到系统接口、参数、字段、认证方式，增加安全风险。

十二、实际选型建议

1. 新 Spring Boot 3 项目

推荐：

OpenAPI3 + springdoc-openapi + Knife4j

或者：

OpenAPI3 + springdoc-openapi + Swagger UI

如果团队偏国内企业后台、测试人员经常用接口文档，建议 Knife4j。

2. 简单项目 / 对外开放接口

推荐：

OpenAPI3 + springdoc-openapi + Swagger UI

理由：

标准、轻量、官方生态更通用

3. 内部管理系统 / 接口多 / 中文团队

推荐：

OpenAPI3 + springdoc-openapi + Knife4j

理由：

页面体验更符合国内团队习惯，功能增强更多

4. 微服务项目

推荐：

每个服务生成 /v3/api-docs
网关统一聚合
Knife4j 或 Swagger UI 统一展示

如果需要更好的聚合体验，可以优先考虑 Knife4j。

十三、最终总结

可以这样记：

OpenAPI3：
接口文档标准，相当于“普通话”。

Swagger3：
围绕 OpenAPI3 的工具和注解生态，相当于“说普通话的一套工具”。

springdoc-openapi：
Spring Boot 项目里的自动翻译器，把 Controller 翻译成 OpenAPI3 JSON。

Swagger UI：
官方风格的网页阅读器，把 OpenAPI3 JSON 展示成接口文档页面。

Knife4j：
增强版网页阅读器，更适合国内团队使用，支持更多文档增强和聚合能力。

最常见组合是：

Spring Boot Controller
  + springdoc-openapi
  + OpenAPI3
  + Swagger UI

或者国内项目常用：

Spring Boot Controller
  + springdoc-openapi
  + OpenAPI3
  + Knife4j

一句话落地建议：

如果只是普通 Spring Boot 项目，用 springdoc-openapi-starter-webmvc-ui 就够；如果是企业内部系统、接口多、希望文档更好用，就用 Knife4j；无论用 Swagger UI 还是 Knife4j，底层核心都是 OpenAPI3。