Java SpringBoot詳解集成以及配置Swagger流程

更新時(shí)間：2021年10月27日 09:47:45 作者：龍弟-idea

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)?？傮w目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來(lái)更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來(lái)始終保持同步

一、swagge簡(jiǎn)介

前后端分離:

后端︰后端控制層，服務(wù)層，數(shù)據(jù)訪問層【后端團(tuán)隊(duì)】

前端:前端控制層，視圖層【前端團(tuán)隊(duì)】

前后端通過(guò)API進(jìn)行交互

前后端相對(duì)獨(dú)立且松耦合

產(chǎn)生問題：前后端集成，前端或者后端無(wú)法做到“及時(shí)協(xié)商，盡早解決”，最終導(dǎo)致問題集中爆發(fā)

解決方法：首先定義schema [ 計(jì)劃的提綱 ]，并實(shí)時(shí)跟蹤最新的API，降低集成風(fēng)險(xiǎn)

前后端分離：前端測(cè)試后端接口:postman
后端提供接口，需要實(shí)時(shí)更新最新的消息及改動(dòng)!

Swagger

號(hào)稱世界上最流行的API框架
Restful Api 文檔在線自動(dòng)生成器 => API 文檔與API 定義同步更新
直接運(yùn)行，在線測(cè)試API
支持多種語(yǔ)言（如：Java，PHP等）
官網(wǎng)：API Documentation & Design Tools for Teams | Swagger

二、SpringBoot集成Swagger

1、新建一個(gè)SpringBoot-web項(xiàng)目

2、添加Maven依賴

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3、編寫HelloController，測(cè)試確保運(yùn)行成功！

4、要使用Swagger，我們需要編寫一個(gè)配置類-SwaggerConfig來(lái)配置 Swagger

@Configuration
@EnableSwagger2        //開啟Swagger2
public class SwaggerConfig {
    
}

5.訪問測(cè)試：http://localhost:8081/swagger-ui.html,可以看到swagger的界面；

三、配置Swagger

1、Swagger實(shí)例Bean是Docket，所以通過(guò)配置Docket實(shí)例來(lái)配置Swaggger。

//配置了Swagger的Docket的bean實(shí)例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
 
    }

2、可以通過(guò)apiInfo()屬性配置文檔信息

    //配置文檔信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("龍弟", "https://blog.csdn.net/weixin_48838340", "聯(lián)系人郵箱");
        return new ApiInfo(
                "龍弟的Swagger學(xué)習(xí)文檔", // 標(biāo)題
                "學(xué)習(xí)演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/weixin_48838340", // 組織鏈接
                contact, // 聯(lián)系人信息
                "Apach 2.0 許可", // 許可
                "許可鏈接", // 許可連接
                new ArrayList<>()// 擴(kuò)展
        );
    }
}

3、Docket 實(shí)例關(guān)聯(lián)上 apiInfo()

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

4.重啟項(xiàng)目

四、配置掃描接口

構(gòu)建Docket時(shí)通過(guò)select()方法配置怎么掃描接口。

    //配置了Swagger的Docket的bean實(shí)例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 通過(guò).select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
                  //any() // 掃描所有，項(xiàng)目中的所有接口都會(huì)被掃描到
                 // none() // 不掃描接口
        // withMethodAnnotation通過(guò)方法上的注解掃描，如withMethodAnnotation(GetMapping.class)只掃描get請(qǐng)求
        // 通過(guò)類上的注解掃描，如.withClassAnnotation(Controller.class)只掃描有controller注解的類中的接口
                .apis(RequestHandlerSelectors.basePackage("com.longdi.swagger.controller"))
                //path()  過(guò)濾什么路徑
                .paths(PathSelectors.ant("/longdi/**"))
                .build();
    };

五、配置Swagger開關(guān)

1、通過(guò)enable()方法配置是否啟用swagger

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false) //配置是否啟用Swagger，如果是false，在瀏覽器將無(wú)法訪問
                .select()// 通過(guò).select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
                .apis(RequestHandlerSelectors.basePackage("com.longdi.swagger.controller"))
                // 配置如何通過(guò)path過(guò)濾,即這里只掃描請(qǐng)求以/longdi開頭的接口
                .paths(PathSelectors.ant("/longdi/**"))
                .build();
    }

2.如何動(dòng)態(tài)配置當(dāng)項(xiàng)目處于test、dev環(huán)境時(shí)顯示swagger

    @Bean
    public Docket docket(Environment environment) {
        // 設(shè)置要顯示swagger的環(huán)境
        Profiles of = Profiles.of("dev", "test");
        // 判斷當(dāng)前是否處于該環(huán)境
        // 通過(guò) enable() 接收此參數(shù)判斷是否要顯示
        boolean b = environment.acceptsProfiles(of);
 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b) //配置是否啟用Swagger，如果是false，在瀏覽器將無(wú)法訪問
                .select()// 通過(guò).select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口
                .apis(RequestHandlerSelectors.basePackage("com.longdi.swagger.controller"))
                // 配置如何通過(guò)path過(guò)濾,即這里只掃描請(qǐng)求以/longdi開頭的接口
                .paths(PathSelectors.ant("/longdi/**"))
                .build();
    }

六、配置API分組

1.如果沒有配置分組，默認(rèn)是default。通過(guò)groupName()方法即可配置分組：

    @Bean
    public Docket docket1(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .groupName("A") ;// 配置分組
        // 省略配置....
    }

2.配置多個(gè)分組只需要配置多個(gè)docket即可

3.重啟看到下面效果

七、實(shí)體配置

1.新建一個(gè)實(shí)體類

@ApiModel為類添加注釋

@ApiModelProperty為類屬性添加注釋

2.只要這個(gè)實(shí)體在請(qǐng)求接口的返回值上（即使是泛型），都能映射到實(shí)體項(xiàng)中：

    //只要我們的接口中，返回值中存在實(shí)體類，它就會(huì)被掃描到Swagger中
    @PostMapping(value="/user")
    public User getUser(){
        return new User();
    }

3.查看效果

4.可以給請(qǐng)求的接口配置一些注釋

    //Operation接口，不是放在類上的，是方法
    @ApiOperation("龍弟的接口")
    @GetMapping("/hello2")
    public String kuang(@ApiParam("這個(gè)名字會(huì)被返回")String username){
        return "hello"+username;
    }