SpringBoot整合Swagger3.0全過程

更新時間：2026年03月13日 15:07:14 作者：bug攻城獅

文章介紹了Swagger3,一個自動生成接口文檔的工具,相比Swagger2,配置更少,使用更方便,文章詳細介紹了如何引入依賴,添加開關注解,訪問Swagger界面,以及如何配置Swagger和引入第三方UI包來美化頁面

一、引言

前后端分離的項目，接口文檔的存在十分重要。與手動編寫接口文檔不同，swagger是一個自動生成接口文檔的工具，只需要在pom文件中引入一個依賴包，然后在代碼中通過注解的方式即可實現(xiàn)文檔的編寫，畢竟在需求不斷變更的環(huán)境下，手動編寫文檔的效率實在太低且不夠同步，swagger的出現(xiàn)，將文檔和代碼融合在一起，再也不需要寫完代碼后再去手動修改文檔了。

二、簡介

Swagger3在Swagger2的基礎上進行了部分升級，與swagger2相比新版的swagger3配置更少，使用更加方便。

一個重要的優(yōu)化是依賴的引入，由之前的多個依賴變更為一個依賴，跟隨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，才能實現(xiàn)生成接口文檔的功能

@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();
    }

    /**
     * 創(chuàng)建一個ApiInfo對象
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文檔標題
                .title("SpringBoot整合Swagger3")
                // 簡介
                .description("更多請咨詢服務開發(fā)者小龍")
                // 作者信息：作者姓名、作者地址、作者郵箱
                .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