SpringBoot中集成Swagger2及簡(jiǎn)單實(shí)用

更新時(shí)間：2023年06月10日 10:11:47 作者：秋天code

使用Swagger你只需要按照它的規(guī)范去定義接口及接口相關(guān)的信息，再通過(guò)Swagger衍生出來(lái)的一系列項(xiàng)目和工具，就可以做到生成各種格式的接口文檔，以及在線接口調(diào)試頁(yè)面等等，這篇文章主要介紹了SpringBoot中集成Swagger2,需要的朋友可以參考下

介紹

Swagger是非常流行的API框架，能夠自動(dòng)生成RESTFul 風(fēng)格的API文檔，還可以在線測(cè)試后臺(tái)接口。
使用Swagger你只需要按照它的規(guī)范去定義接口及接口相關(guān)的信息，再通過(guò)Swagger衍生出來(lái)的一系列項(xiàng)目和工具，就可以做到生成各種格式的接口文檔，以及在線接口調(diào)試頁(yè)面等等。
前后端分離的開(kāi)發(fā)模式下，前端通過(guò)后端的API文檔來(lái)進(jìn)行開(kāi)發(fā)和聯(lián)調(diào)，效率更高。
Swagger就是幫助后端生成API文檔的工具

簡(jiǎn)單使用

在SpringBoot中集成Swagger2，（等會(huì)說(shuō)一個(gè)更簡(jiǎn)單的用法）。

引入依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

配置類

@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * 將負(fù)責(zé)生成摘要的Bean提供出去
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否開(kāi)啟 (true 開(kāi)啟  false隱藏。生產(chǎn)環(huán)境建議隱藏)
                //.enable(false)
                .select()
                //掃描的路徑包,設(shè)置basePackage會(huì)將包下的所有被@Api標(biāo)記類的所有方法作為api
                .apis(RequestHandlerSelectors.basePackage("com.liumingkai.controller"))
                //指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 用來(lái)設(shè)置文檔元信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //設(shè)置文檔標(biāo)題(API名稱)
                .title("SpringBoot中使用Swagger2接口規(guī)范")
                //文檔描述
                .description("接口說(shuō)明")
                //版本號(hào)
                .version("1.0.0")
                .build();
    }
}

使用
因?yàn)镾wagger幫助我們生成RestFul風(fēng)格的文檔，所以被修飾的接口方法必須是類似于@GetMapping、@PostMapping、@DeleteMapping，不能是一個(gè)籠統(tǒng)的@RequestMapping
下面會(huì)有詳細(xì)的常用注解說(shuō)明，此處只是想要來(lái)快速看一下效果

@RestController
@RequestMapping("/user")
@Api(value = "測(cè)試接口", tags = "用戶登錄接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登錄", tags = "登錄接口")
    public String login(String username, String password){
        return "登錄成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登錄",tags = "退出登錄")
    public String logout(String username){
        return "退出登錄成功";
    }
}

接下來(lái)訪問(wèn)http://ip:port/swagger-ui.html，會(huì)看到

SpringBoot版本與Swagger版本的沖突問(wèn)題

如果你訪問(wèn)Swagger的文檔地址后，發(fā)現(xiàn)是404，無(wú)法訪問(wèn)，那么大概是SpringBoot的版本問(wèn)題

注意：
如果你的SpringBoot是2.6.x及更高，那么與Swagger2是不兼容的，因?yàn)镾pringMVC的處理映射匹配的方式發(fā)生了變化。
需要在SpringBoot的配置文件中通過(guò)添加配置來(lái)使springboot2.6.x以后的版本來(lái)適配Swagger2
不要試圖通過(guò)@EnableWebMvc來(lái)解決，同樣會(huì)導(dǎo)致404

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

常用注解

Swagger的核心就是我們常用的這幾個(gè)注解

@Api

一般用來(lái)標(biāo)注在Controller上，注意此Controller要是一個(gè)RestController。

注解	說(shuō)明
@Api	一般用在Controller類上，Swagger會(huì)掃描被此注解標(biāo)注的類，并生成一個(gè)文檔分類
@ApiOperation	用在接口方法上，對(duì)該接口方法進(jìn)行描述
@ApiModel	用在實(shí)體類上，為此實(shí)體類生成說(shuō)明文檔
@ApiParam	用來(lái)接口參數(shù)上，用來(lái)對(duì)此請(qǐng)求參數(shù)做說(shuō)明
@ApiModelProperty	用來(lái)實(shí)體類中的屬性上，對(duì)此屬性做說(shuō)明

@RestController
@RequestMapping("/user")
@Api(value = "測(cè)試接口", tags = "用戶登錄接口")
public class LoginController {
}

屬性：

value ，該接口模塊的名稱，沒(méi)啥用，對(duì)于程序員來(lái)說(shuō)起一個(gè)標(biāo)識(shí)作用
tags，該接口模塊在文檔中的標(biāo)簽名，會(huì)在API文檔中顯示。
- 如果未指定此模塊的tags標(biāo)簽，那么就會(huì)使用Controller的類名作為tags名稱
- tags可以認(rèn)為是一個(gè)分類，名稱相同的內(nèi)容，會(huì)被歸為一個(gè)分類。
hidden，隱藏該模塊，默認(rèn)是false，不隱藏，隱藏后該模塊不會(huì)出現(xiàn)在api文檔中

@ApiOperation

次注解用在方法上，對(duì)該接口進(jìn)行描述。

@RestController
@RequestMapping("/user")
@Api(value = "測(cè)試接口", tags = "用戶登錄接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登錄", tags = "用戶登錄接口")
    public String login(String username, String password){
        return "登錄成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登錄",tags = "用戶登錄接口")
    public String logout(String username){
        return "退出登錄成功";
    }
}

屬性：

value，該接口方法的名稱，必填的屬性，用來(lái)對(duì)接口標(biāo)識(shí)作用
tags，用來(lái)指定該接口屬于的標(biāo)簽，tags相同的接口方法，在文檔中會(huì)屬于同一個(gè)分類下
- 一個(gè)接口方法可以屬于多個(gè)分類
hidden，是否隱藏該接口，默認(rèn)是false

@ApiParam

用在接口的參數(shù)上，用來(lái)對(duì)該參數(shù)進(jìn)行修飾
屬性：

value，標(biāo)識(shí)作用
name，該參數(shù)的名稱，如果省略該屬性，則會(huì)以參數(shù)名來(lái)作為名稱在文檔中顯示
required，是否必選，默認(rèn)是false，此屬性最常用

@RestController
@RequestMapping("/user")
@Api(value = "測(cè)試接口", tags = "用戶登錄接口")
public class LoginController {
    @PostMapping("/login")
    @ApiOperation(value = "登錄", tags = "用戶登錄接口")
    public String login(@ApiParam(name="username", required = true) String username, @ApiParam(name="password",required = true) String password){
        return "登錄成功"+username+password;
    }
    @PostMapping("/logout")
    @ApiOperation(value="退出登錄",tags = "用戶登錄接口")
    public String logout(String username){
        return "退出登錄成功";
    }
}

@ApiResponse

用在方法上，對(duì)接口的返回內(nèi)容進(jìn)行描述
常用屬性：

code，響應(yīng)的狀態(tài)碼
message，返回的描述信息
response，用來(lái)指定返回的實(shí)體類，也就是真正的響應(yīng)數(shù)據(jù)

    @GetMapping("/detail/{username}")
    @ApiOperation("獲取用戶詳情信息")
    @ApiResponse(code = 200,message = "查詢成功",response = User.class)
    public User getDetail(@ApiParam(value = "要查詢的用戶名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiResponses

如果返回的結(jié)果有多種，則可以使用@ApiResponses注解，此注解只有一個(gè)屬性value，是一個(gè)@ApiResponse的數(shù)組。
其中包含多個(gè)@ApiResponse，每個(gè)@ApiResponse都是一種響應(yīng)結(jié)果

    @GetMapping("/detail/{username}")
    @ApiOperation("獲取用戶詳情信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = User.class),
            @ApiResponse(code = 403, message = "你還沒(méi)有權(quán)限")
    }
    )
    public User getDetail(@ApiParam(value = "要查詢的用戶名", required = true) @PathVariable("username") String username) {
        User user = new User();
        user.setAge(18);
        user.setUsername("zhagnsan");
        user.setPassword("123156");
        user.setSex("男");
        return user;
    }

@ApiModel

用在實(shí)體類上，用來(lái)對(duì)此實(shí)體類進(jìn)行描述。
如果你的返回值類型或參數(shù)類型是實(shí)體類類型，那么Swagger就會(huì)使用@ApiModel對(duì)其進(jìn)行描述

屬性：

value，標(biāo)識(shí)名，如果不填，則會(huì)以類名作為valuedescription，類的描述信息
實(shí)體類上標(biāo)注了此類后，會(huì)將所有的屬性進(jìn)行描述

@ApiModel(value="用戶實(shí)體類",description = "這是返回的實(shí)體類的描述信息")
@Data
public class User {
    private String username;
    private String password;
    private String sex;
    private Integer age;
}

一般都是直接@ApiModel注解，不用屬性

@ApiProperty

如果需要對(duì)實(shí)體類中的屬性進(jìn)行單獨(dú)的設(shè)置，那么就需要使用@ApiProperty屬性了
常用屬性：

value，標(biāo)識(shí)
name，名稱，在文檔中的顯示的名稱
hidden，是否隱藏此屬性
required，此屬性是否必須

@ApiModel(value="用戶實(shí)體類",description = "這是返回的實(shí)體類的描述信息")
@Data
public class User {
    @ApiModelProperty(value = "用戶名",required = true)
    private String username;
    @ApiModelProperty(hidden = true)
    private String password;
    private String sex;
    private Integer age;
}

參考文檔：
SpringBoot與Swagger2版本不兼容的問(wèn)題??！
Failed to start bean ‘documentationPluginsBootstrapper‘； nested exception is java.lang.NullPointerEx_Shipley_Leo的博客-CSDN博客
 Springboot ? Swagger各版本整理_swaager 版本_qq_33334411的博客-CSDN博客
 swagger-ui.html頁(yè)面無(wú)法打開(kāi)解決方案_Alphathur的博客-CSDN博客

到此這篇關(guān)于SpringBoot中集成Swagger2的文章就介紹到這了,更多相關(guān)SpringBoot集成Swagger2內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: