SpringBoot中集成Swagger2及簡單實用

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

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

介紹

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

簡單使用

在SpringBoot中集成Swagger2，（等會說一個更簡單的用法）。

引入依賴

<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())
                //是否開啟 (true 開啟  false隱藏。生產(chǎn)環(huán)境建議隱藏)
                //.enable(false)
                .select()
                //掃描的路徑包,設(shè)置basePackage會將包下的所有被@Api標(biāo)記類的所有方法作為api
                .apis(RequestHandlerSelectors.basePackage("com.liumingkai.controller"))
                //指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 用來設(shè)置文檔元信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //設(shè)置文檔標(biāo)題(API名稱)
                .title("SpringBoot中使用Swagger2接口規(guī)范")
                //文檔描述
                .description("接口說明")
                //版本號
                .version("1.0.0")
                .build();
    }
}

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

@RestController
@RequestMapping("/user")
@Api(value = "測試接口", 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 "退出登錄成功";
    }
}

接下來訪問http://ip:port/swagger-ui.html，會看到

SpringBoot版本與Swagger版本的沖突問題

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

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

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

常用注解

Swagger的核心就是我們常用的這幾個注解

@Api

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

注解	說明
@Api	一般用在Controller類上，Swagger會掃描被此注解標(biāo)注的類，并生成一個文檔分類
@ApiOperation	用在接口方法上，對該接口方法進行描述
@ApiModel	用在實體類上，為此實體類生成說明文檔
@ApiParam	用來接口參數(shù)上，用來對此請求參數(shù)做說明
@ApiModelProperty	用來實體類中的屬性上，對此屬性做說明

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

屬性：

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

@ApiOperation

次注解用在方法上，對該接口進行描述。

@RestController
@RequestMapping("/user")
@Api(value = "測試接口", 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，該接口方法的名稱，必填的屬性，用來對接口標(biāo)識作用
tags，用來指定該接口屬于的標(biāo)簽，tags相同的接口方法，在文檔中會屬于同一個分類下
- 一個接口方法可以屬于多個分類
hidden，是否隱藏該接口，默認(rèn)是false

@ApiParam

用在接口的參數(shù)上，用來對該參數(shù)進行修飾
屬性：

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

@RestController
@RequestMapping("/user")
@Api(value = "測試接口", 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

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

code，響應(yīng)的狀態(tài)碼
message，返回的描述信息
response，用來指定返回的實體類，也就是真正的響應(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注解，此注解只有一個屬性value，是一個@ApiResponse的數(shù)組。
其中包含多個@ApiResponse，每個@ApiResponse都是一種響應(yīng)結(jié)果

    @GetMapping("/detail/{username}")
    @ApiOperation("獲取用戶詳情信息")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = User.class),
            @ApiResponse(code = 403, message = "你還沒有權(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ù)類型是實體類類型，那么Swagger就會使用@ApiModel對其進行描述

屬性：

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

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

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

@ApiProperty

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

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

@ApiModel(value="用戶實體類",description = "這是返回的實體類的描述信息")
@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版本不兼容的問題?。?br />Failed to start bean ‘documentationPluginsBootstrapper‘； nested exception is java.lang.NullPointerEx_Shipley_Leo的博客-CSDN博客
 Springboot ? Swagger各版本整理_swaager 版本_qq_33334411的博客-CSDN博客
 swagger-ui.html頁面無法打開解決方案_Alphathur的博客-CSDN博客

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

您可能感興趣的文章: