Swagger（丝袜哥）3.0 官方 Starter 终于出了，真的香吗？！

关注

原创最新推荐文章于 2026-06-15 09:15:41 发布 551 阅读 AI 写同款· GEO 优化 ›

Dubbo集成Knife4j (Swagger 生成doc.html) Apache Dubbo™ 是一款高性能Java RPC框架。Apache Dubbo Spring Boot Project使得使用Dubbo作为RPC框架轻松创建Spring Boot应用程序。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。阅读详情

点击上方“芋道源码”，选择“设为星标”

管她前浪，还是后浪？

能浪的浪，才是好浪！

每天 8:55 更新文章，每天掉亿点点头发...

源码精品专栏

摘要: 原创出处 http://www.iocoder.cn/Spring-Boot/Swagger-Starter/ 「芋道源码」欢迎转载，保留摘要，谢谢！

1. 概述
2. 快速体验
3. 自定义配置
4. 自定义 Starter
666. 彩蛋

1. 概述

周末，不讲武德的狗芳跟我说，Swagger 官方 Starter 出来了，可以自动配置，真的香！

我拍了拍他的????头，这都出来四个月了，哥一早就体验过，并没有想象中的好用。

SpringFox 3.0.0 发布

狗芳表示不服，为什么不好用？

我又拍了拍他的????头，虽然提供了自动配置的功能，但是并未提供常用的配置项。

友情提示：对 Swagger 不了解的胖友，可以阅读下我写的《芋道 Spring Boot API 接口文档 Swagger 入门》文章，好看到爆炸~

2. 快速体验

我们先来快速体验下 Swagger 官方 Starter，体验下其提供的自动配置的功能。

新建一个示例项目，最终代码会如下图：

示例项目

良心艿：完整的代码，胖友可以访问 https://github.com/YunaiV/SpringBoot-Labs/tree/master/lab-24/lab-24-apidoc-swagger 地址。

嘿嘿~给个 star 噢！

2.1 引入依赖

在 pom.xml 文件中，引入 springfox-boot-starter 的依赖。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.11.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>lab-24-apidoc-swagger-starter</artifactId>

    <dependencies>
        <!-- 实现对 Spring MVC 的自动配置 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 实现对 Swagger 的自动配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
    </dependencies>

</project>

注意，最低支持使用 SpringBoot 版本为 2.2+ 。

版本差异：是否使用 Starter 的依赖对比如下：

依赖对比

2.2 示例代码

下面，我们来编写用于展示 Swagger 功能的示例代码，和是否使用 Starter 并没有任何差别。

① 创建 UserController 类，添加相应的 Swagger 注解。代码如下：

@RestController
@RequestMapping("/users")
@Api(tags = "用户 API 接口")
public class UserController {

    @GetMapping("/list")
    @ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试，所以返回用户全列表")
    public List<UserVO> list() {
        // 查询列表
        List<UserVO> result = new ArrayList<>();
        result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
        result.add(new UserVO().setId(2).setUsername("woshiyutou"));
        result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));
        // 返回列表
        return result;
    }

    @GetMapping("/get")
    @ApiOperation("获得指定用户编号的用户")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
    public UserVO get(@RequestParam("id") Integer id) {
        // 查询并返回用户
        return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());
    }

    @PostMapping("add")
    @ApiOperation("添加用户")
    public Integer add(UserAddDTO addDTO) {
        // 插入用户记录，返回编号
        Integer returnId = UUID.randomUUID().hashCode();
        // 返回用户编号
        return returnId;
    }

    @PostMapping("/update")
    @ApiOperation("更新指定用户编号的用户")
    public Boolean update(UserUpdateDTO updateDTO) {
        // 更新用户记录
        Boolean success = true;
        // 返回更新是否成功
        return success;
    }

    @PostMapping("/delete")
    @ApiOperation(value = "删除指定用户编号的用户")
    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
    public Boolean delete(@RequestParam("id") Integer id) {
        // 删除用户记录
        Boolean success = false;
        // 返回是否更新成功
        return success;
    }

}

UserAddDTO
UserUpdateDTO
UserVO

② 创建 Application 类，用于 SpringBoot 应用的启动。代码如下：

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

2.3 简单测试

一切准备就绪，执行 Application 启动 SpringBoot 应用。

使用浏览器，访问 http://127.0.0.1:8080/swagger-ui/ 地址，进入 Swagger UI 界面。如下图所示：

版本差异：新版本的 Swagger UI 界面的地址，是 /swagger-ui/，而不是老版本的 /swagger-ui.html。

Swagger UI 界面

如此，我们已经完成了 Swagger 的快速集成与体验，还是非常方便。

3. 自定义配置

当我们想进行 Swagger 接口文档的自定义时，例如说修改 title 标题、description 描述等等信息时，却发现官方 Starter 并未提供对应的配置项。如下图所示：

配置项

这就导致，我们不得不创建 Configuration 类，进行自定义配置。下面，我们来演示下。

3.1 SwaggerConfiguration

创建 SwaggerConfiguration 类，设置自定义的 title 标题、description 描述等等信息。代码如下：

@Configuration
// @EnableSwagger2 无需使用该注解
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        // 创建 Docket 对象
        return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用 Swagger2
                .apiInfo(this.apiInfo()) // 设置 API 信息
                // 扫描 Controller 包路径，获得 API 接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.controller"))
                .paths(PathSelectors.any())
                // 构建出 Docket 对象
                .build();
    }

    /**
     * 创建 API 信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口文档示例")
                .description("我是一段描述")
                .version("1.0.0") // 版本号
                .contact(new Contact("芋艿", "http://www.iocoder.cn", "zhijiantianya@gmail.com")) // 联系人
                .build();
    }

}