快捷導(dǎo)航

SpringBoot整合Swagger3的流程詳解

更新時(shí)間：2024年01月04日 09:20:14 作者：Splaying

這篇文章主要介紹了SpringBoot整合Swagger3的流程詳解,Swagger最核心的類就是Docket、它可以配置作者信息、掃描類型,在SwaggerConfig配置類,添加@Configuration和@EnableOpenApi注解,需要的朋友可以參考下

1、創(chuàng)建項(xiàng)目

首先創(chuàng)建一個(gè)SpringBoot項(xiàng)目，隨便勾選幾個(gè)項(xiàng)目依賴，我選擇了web、thymeleaf、lombok。

在這里插入圖片描述

添加項(xiàng)目依賴，這里使用Swagger3（與Swagger2略有差異），并且添加一個(gè)好看一點(diǎn)的ui界面

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2、配置Swagger

Swagger最核心的類就是Docket、它可以配置作者信息、掃描類型…
首先創(chuàng)建一個(gè)SwaggerConfig配置類，添加@Configuration和@EnableOpenApi注解。
然后再向里面丟入Docket類的Bean實(shí)例，然后默認(rèn)就可以訪問(wèn)了

@Configuration
@EnableOpenApi
public class SwaggerConfig {
	@Bean
    Docket docket(){
		return new Docket(DocumentationType.SWAGGER_2)
	}
}

訪問(wèn)localhost:8080/doc.html頁(yè)面就可以看到了，/error接口的8種請(qǐng)求方式默認(rèn)會(huì)出現(xiàn)在文檔中，以及一些可以配置的信息

在這里插入圖片描述

3、Swagger配置

上圖紅字的位置都是可以進(jìn)行配置的，可以針對(duì)不同人寫的不同接口等信息放在不同的分組中。

3.1、配置主頁(yè)信息

其實(shí)這里有用的沒(méi)幾個(gè)，基本上很多信息都是默認(rèn)給出。

@Bean
public ApiInfo apiInfo(){
    return new ApiInfo("這是Swagger文檔",				//title名稱
            "歸來(lái)仍是少年",								//簡(jiǎn)介
            "1.0",										//版本
            "urn:tos",									//服務(wù)url
            new Contact(								//配置聯(lián)系作者的方式
            	"xxx",									//作者名稱
            	"https://www.baidu.com",				//連接
            	"xxxx@qq.com"),							//作者郵箱
            "Apache 2.0",								//許可證
            "http://www.apache.org/licenses/LICENSE-2.0",		//許可證地址
            new ArrayList<>());							//供應(yīng)商的拓展
}

3.2、配置Docket信息

上面配置了主頁(yè)面的一些信息，然后需要將這些信息注入到Docket中。
另外配置掃描接口的路徑、過(guò)濾、分組以及是否開(kāi)啟等
當(dāng)然這里可以拿到環(huán)境配置文件、可以根據(jù)不同的環(huán)境決定是否開(kāi)啟；一般情況下這些接口都是在開(kāi)發(fā)環(huán)境中進(jìn)行展示的，實(shí)際交付的時(shí)候是不會(huì)提供的。
Docket是采用鏈?zhǔn)骄幊痰男问竭M(jìn)行配置，當(dāng)存在多個(gè)Docket時(shí)可以通過(guò)不同的分組名稱進(jìn)行區(qū)分

@Bean
Docket docket_A(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("TestA");
}

@Bean
Docket docket_B (){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("TestB");
}


@Bean
Docket docket(Environment environment){

    boolean result = environment.acceptsProfiles(Profiles.of("dev"));

    return new Docket(DocumentationType.SWAGGER_2)
    		.groupName("Splay")				//默認(rèn)分組Default改為Splay
            .apiInfo(apiInfo())				//注入主頁(yè)面信息
            .enable(true)                   //是否啟用swagger
            .select()						//掃描
            /**
             * apis指定要掃描的方式
             * 1. basePackage(): 指定掃描的包
             * 2. any(): 全部掃描
             * 3. none(): 都不掃描
             * 4. withClassAnnotation(): 通過(guò)類注解掃描
             * 5. withMethodAnnotation(): 通過(guò)方法上的注解掃描
             */
            .apis(RequestHandlerSelectors.basePackage("com.splay.controller"))
            /**
             * paths過(guò)濾不需要
             * 1. ant(): 制定路徑
             * 2. none(): 全都不過(guò)濾
             * 3. any(): 都過(guò)濾
             * 4. regex(): 正則表達(dá)式
             */
            //.paths(PathSelectors.ant("/splay/**"))		//過(guò)濾不需要的路徑
            .build();
}

3.3、編寫Controller

上面通過(guò)apis方法配置只掃描com.splay.controller包下的所有接口

@Controller
public class RouterController {
    
    @GetMapping("/hello")
    @ResponseBody
    public String toHello(){
        return "Hello Swagger";
    }
}

這里可以綁定開(kāi)啟的環(huán)境，通過(guò)Environment拿到進(jìn)行判斷再?zèng)Q定是否開(kāi)啟。

在這里插入圖片描述

3.4、效果圖

在這里插入圖片描述

4、注解的使用

Swagger提供了很多的注解，幾乎所有需要提供展示的東西都可以使用注解來(lái)開(kāi)啟。
@Api配置Controller類、@ApiModel類可以給pojo進(jìn)行展示、@ApiModelProperty配置pojo的屬性、@ApiOperation配置方法…

4.1、pojo的配置

當(dāng)返回值存在當(dāng)前配置的pojo時(shí)，可以在model頁(yè)面看到這些信息。

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用戶類" )
public class User {

    @ApiModelProperty("用戶名")
    private String username;

    @ApiModelProperty("密碼")
    private String password;

}

4.2、Controller的配置

Controller的名稱將會(huì)展示為tags屬性中的值

@Controller
@Api(tags = "路由控制類")
public class RouterController {
	
}

4.3、接口名稱的配置

@PostMapping("/user")
@ResponseBody
@ApiOperation("返回用戶信息")			//接口名稱、以及參數(shù)
public User sendUserMessage(@ApiParam("用戶帳號(hào)") String username){
    System.out.println(username);
    return new User("admin", "123456");
}