首页 > 软件编程 > java > SpringBoot整合Swagger3.0

SpringBoot整合Swagger3.0全过程

2026-03-13 15:07:15 作者：bug攻城狮

文章介绍了Swagger3,一个自动生成接口文档的工具,相比Swagger2,配置更少,使用更方便,文章详细介绍了如何引入依赖,添加开关注解,访问Swagger界面,以及如何配置Swagger和引入第三方UI包来美化页面

一、引言

前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，swagger是一个自动生成接口文档的工具，只需要在pom文件中引入一个依赖包，然后在代码中通过注解的方式即可实现文档的编写，毕竟在需求不断变更的环境下，手动编写文档的效率实在太低且不够同步，swagger的出现，将文档和代码融合在一起，再也不需要写完代码后再去手动修改文档了。

二、简介

Swagger3在Swagger2的基础上进行了部分升级，与swagger2相比新版的swagger3配置更少，使用更加方便。

一个重要的优化是依赖的引入，由之前的多个依赖变更为一个依赖，跟随springboot-starter风格，同时引入了新的开关注解 @EnableOpenApi 以代替 @EnableSwagger2 。

因此，集成工作变得更加的简便了，必要工作只有两个，添加swagger3的starter依赖包，在springboot主启动类添加 @EnableOpenApi 开关注解。

三、快速入门

（一）引入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

（二）主启动类添加开关注解 @EnableOpenApi

作用：表示开启生成接口文档功能，只有开启了OpenApi，才能实现生成接口文档的功能

@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

（三）访问Swagger界面

访问地址（默认端口号是8080）：http://localhost:8080/swagger-ui/index.html

四、进阶使用

（一）配置Swagger

// 表明当前类是配置类
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // 为api选择启动生成器
                .select()
                // 指定要生成api文档的根包
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径配置
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建一个ApiInfo对象
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("SpringBoot整合Swagger3")
                // 简介
                .description("更多请咨询服务开发者小龍")
                // 作者信息：作者姓名、作者地址、作者邮箱
                .contact(new Contact("小龍", "https://blog.csdn.net/wangzhilong1996", "123456@qq.com"))
                // 版本号
                .version("1.0")
                .build();
    }
}

（二）引入第三方UI包

原生的ui页面并不美观，可以使用第三方的ui包来美化页面，当然，市面上的第三方ui包有很多，大家可以找一个自己喜欢的，不一定用我的。

<!-- swagger 第三方ui包 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

访问地址：http://localhost:8080/doc.html

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。