3、swagger調試

Swagger：

1、將項目中所有的接口展現在頁面上，這樣后端程序員就不需要專門為前端使用者編寫專門的接口文檔；

2、當接口更新之后，只需要修改代碼中的Swagger描述就可以實時生成新的接口文檔了，從而規避了接口文檔老舊不能使用的問題；

3、通過Swagger頁面，可以直接進行接口調用，降低了項目開發階段的調試成本（在線測試）

 

Swagger配置：

1、添加swagger相關依賴：

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

2、Swagger的configuration配置：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean //配置docket以配置Swagger具體參數
    public Docket docket(Environment environment) {

        //動態配置項目所屬什么環境時來顯示swagger
        // 設置要顯示swagger的環境
//        Profiles of = Profiles.of("dev", "test");

        // 判斷當前是否處於該環境
        // 通過enable()方法接收此參數判斷是否要顯示
//        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                //配置文檔頁面信息
                .apiInfo(apiInfo())

                //動態配置是否啟用Swagger，如果是false，在瀏覽器將無法訪問
//                .enable(flag)

                //配置分組
                //配置多個分組只需要配置多個docket即可，不同docket有不同組名
                .groupName("組名")

                //構建Docket時通過select()方法掃描接口
                .select()


                //RequestHandlerSelectors：配置要掃描接口的方式
                    //1、掃描所有，項目中的所有接口都會被掃描到：any()
                    //2、不掃描接口：none()
                    //3、掃描方法上的注解：withMethodAnnotation（），
                            // 如withMethodAnnotation(GetMapping.class)只掃描get請求
                    //4、掃描類上的注解，參數是一個反射對象：withClassAnnotation（），
                            // 如.withClassAnnotation(Controller.class)只掃描有controller注解的類中的接口
                    //5、指定要掃描的包路徑：basePackage(final String basePackage)
                //例：.apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                .apis(RequestHandlerSelectors.basePackage("控制類所在包名"))

                //配置如何通過path過濾,即這里只掃描請求以/controller開頭的接口
                    //1、任何請求都掃描：any()
                    //2、任何請求都不掃描：none()
                    //3、通過正則表達式控制：regex(final String pathRegex)
                    //4、通過ant()控制：ant(final String antPattern)
                //例：.paths(PathSelectors.ant("/controller/**"))
                .paths(PathSelectors.ant("控制類中@RequestMapping中的路徑"))
                .build();
    }

    //配置文檔信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("聯系人名字", "http://xxx.xxx.com/聯系人訪問鏈接", "聯系人郵箱");
        return new ApiInfo(
                "Swagger的學習筆記", // 標題
                "如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/組織鏈接", // 組織鏈接
                contact, // 聯系人信息
                "Apach 2.0 許可", // 許可
                "許可鏈接", // 許可連接
                new ArrayList<>()// 擴展
        );
    }

    //配置分組一
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }

    //配置分組二
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
}

3、測試訪問：

http://localhost:8080/swagger-ui.html

 

Swagger常用注解：

1、@Api詳解：

用於標注一個Controller

屬性	描述
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置為true 將在文檔中隱藏

 

2、@ApiOperation詳解：

用於對一個操作或HTTP方法進行描述

屬性	描述
value	url的路徑值
tags	如果設置這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置
hidden	配置為true 將在文檔中隱藏
response	返回的對象
responseContainer	這些對象是有效的 "List", "Set" or "Map".，其他無效
httpMethod	"GET","HEAD","POST","PUT","DELETE","OPTIONS"and"PATCH"
code	http的狀態碼 默認 200
extensions	擴展屬性

3、@ApiParam詳解：

用於請求方法中，定義api參數的注解

屬性	描述
name	屬性名稱
value	屬性值
defaultValue	默認屬性值
allowableValues	可以不配置
required	是否屬性必填
access	不過多描述
allowMultiple	默認為false
hidden	隱藏該屬性
example	舉例子

 

4、@ApiImplicitParams、@ApiImplicitParam詳解：

（1）、@ApiImplicitParams：用在請求的方法上，包含一組參數說明

（2）、@ApiImplicitParam：對單個參數的說明

屬性	描述
name	參數名
value	參數的說明、描述
required	參數是否必須必填
paramType	參數放在哪個地方  query --> 請求參數的獲取：@RequestParam header --> 請求參數的獲取：@RequestHeader path（用於restful接口）--> 請求參數的獲取：@PathVariable body（請求體）--> @RequestBody User user form（普通表單提交）
dataType	參數類型，默認String，其它值dataType="Integer"
defaultValue	參數的默認值

5、@ApiModel、@ApiModelProperty詳解：

（1）、@ApiModel：用於描述一個Model的信息

（2）、@ApiModelProperty：用來描述一個Model的屬性。