SpringBoot整合knife4j

官網說明及用法：

簡介

swagger-bootstrap-ui是springfox-swagger的增強UI實現，為Java開發者在使用Swagger的時候，能擁有一份簡潔、強大的接口文檔體驗

核心功能

該UI增強包主要包括兩大核心功能：文檔說明 和 在線調試

• 文檔說明：根據Swagger的規范說明，詳細列出接口文檔的說明，包括接口地址、類型、請求示例、請求參數、響應示例、響應參數、響應碼等信息，使用swagger-bootstrap-ui能根據該文檔說明，對該接口的使用情況一目了然。

• 在線調試：提供在線接口聯調的強大功能，自動解析當前接口參數,同時包含表單驗證，調用參數可返回接口響應內容、headers、Curl請求命令實例、響應時間、響應狀態碼等信息，幫助開發者在線調試，而不必通過其他測試工具測試接口是否正確,簡介、強大。

UI增強

同時，swagger-bootstrap-ui在滿足以上功能的同時，還提供了文檔的增強功能，這些功能是官方swagger-ui所沒有的，每一個增強的功能都是貼合實際,考慮到開發者的實際開發需要,是比不可少的功能，主要包括：

• 個性化配置：通過個性化ui配置項，可自定義UI的相關顯示信息

• 離線文檔：根據標准規范，生成的在線markdown離線文檔，開發者可以進行拷貝生成markdown接口文檔，通過其他第三方markdown轉換工具轉換成html或pdf，這樣也可以放棄swagger2markdown組件

• 接口排序：自1.8.5后，ui支持了接口排序功能，例如一個注冊功能主要包含了多個步驟,可以根據swagger-bootstrap-ui提供的接口排序規則實現接口的排序，step化接口操作，方便其他開發者進行接口對接

UI特點

• 以markdown形式展示文檔,將文檔的請求地址、類型、請求參數、示例、響應參數分層次依次展示,接口文檔一目了然,方便開發者對接
• 在線調試欄除了自動解析參數外,針對必填項着顏色區分,同時支持tab鍵快速輸入上下切換.調試時可自定義Content-Type請求頭類型
• 個性化配置項,支持接口地址、接口description屬性、UI增強等個性化配置功能
• 接口排序,支持分組及接口的排序功能
• 支持markdown文檔離線文檔導出,也可在線查看離線文檔
• 調試信息全局緩存,頁面刷新后依然存在,方便開發者調試
• 以更人性化的treetable組件展示Swagger Models功能
• 響應內容可全屏查看,針對響應內容很多的情況下，全屏查看，方便調試、復制
• 文檔以多tab方式可顯示多個接口文檔
• 請求參數欄請求類型、是否必填着顏色區分
• 主頁中粗略統計接口不同類型數量
• 支持接口在線搜索功能
• 左右菜單和內容頁可自由拖動寬度
• 支持自定義全局參數功能，主頁包括header及query兩種類型
• i18n國際化支持,目前支持：中文簡體、中文繁體、英文
• JSR-303 annotations 注解的支持

UI效果圖

個性化設置

個性化設置功能是SwaggerBootstrapUi針對本身Ui特點提供的個性化設置功能,主要包括：

• 開啟請求參數緩存
• 菜單Api地址顯示
• 分組tag顯示description說明屬性
• 開啟RequestMapping接口類型重復地址過濾
• 開啟SwaggerBootstrapUi增強功能.

功能目錄：文檔管理 -> 個性化設置

開啟請求參數緩存

此功能在在線調試時可見效果,當針對每個接口點擊發送調試查看后,后面打開該接口再調試時,默認為保留上一次發送的接口參數信息

如果不想開啟此緩存,不勾選此項即可.默認為true,即開啟狀態

菜單Api地址顯示

菜單Api地址顯示是在左側菜單不顯示api地址信息,默認為false,即不顯示,默認效果如下圖 

如果需要左側菜單欄顯示接口地址,則勾選此項接口,顯示效果圖如下：

分組tag顯示description說明屬性

tag是否顯示代碼中的description屬性,默認為false,及不顯示，如果勾選顯示description屬性,效果圖如下：

開啟RequestMapping接口類型重復地址過濾

針對后端RequestMapping注解類型的接口,如果開發者沒有指定接口類型,默認使用Swagger會生成七個不同類型的接口地址,效果圖如下：

再某些情況下,開發者可能需要過濾,簡化重復的接口文檔,此時,開發者通過勾選此選項,並在后面選擇顯示接口類型的選項,SwaggerBootstrapUi會根據此選項自動過濾

例如勾選，然后默認顯示Post類型，則效果如下：

此項默認為false,即不開啟此項(不過濾).

開啟SwaggerBootstrapUi增強功能

全局搜索

SwaggerBootstrapUi提供了全局搜索功能,當開發者不清楚某一接口時,可使用搜索功能快速定位到接口文檔

搜索關鍵字主要包括：URL地址、接口說明、方法類型、接口描述

全局參數

SwaggerBootstrapUi提供基於UI臨時設置全局參數功能,例如后台全局token參數等.

目前全局參數功能主要提供兩種參數類型：query(表單)、header(請求頭)

該功能是在還沒有支持全局參數時臨時配置的功能，如果后端Swagger有配置全局參數，該功能可以無視

功能目錄：文檔管理 -> 全局參數設置

個性化設置

個性化設置功能是SwaggerBootstrapUi針對本身Ui特點提供的個性化設置功能,主要包括：

• 開啟請求參數緩存
• 菜單Api地址顯示
• 分組tag顯示description說明屬性
• 開啟RequestMapping接口類型重復地址過濾
• 開啟SwaggerBootstrapUi增強功能.

功能目錄：文檔管理 -> 個性化設置

開啟請求參數緩存

此功能在在線調試時可見效果,當針對每個接口點擊發送調試查看后,后面打開該接口再調試時,默認為保留上一次發送的接口參數信息

如果不想開啟此緩存,不勾選此項即可.默認為true,即開啟狀態

菜單Api地址顯示

菜單Api地址顯示是在左側菜單不顯示api地址信息,默認為false,即不顯示,默認效果如下圖 

如果需要左側菜單欄顯示接口地址,則勾選此項接口,顯示效果圖如下：

分組tag顯示description說明屬性

tag是否顯示代碼中的description屬性,默認為false,及不顯示，如果勾選顯示description屬性,效果圖如下：

開啟RequestMapping接口類型重復地址過濾

針對后端RequestMapping注解類型的接口,如果開發者沒有指定接口類型,默認使用Swagger會生成七個不同類型的接口地址,效果圖如下：

再某些情況下,開發者可能需要過濾,簡化重復的接口文檔,此時,開發者通過勾選此選項,並在后面選擇顯示接口類型的選項,SwaggerBootstrapUi會根據此選項自動過濾

例如勾選，然后默認顯示Post類型，則效果如下：

此項默認為false,即不開啟此項(不過濾).

開啟SwaggerBootstrapUi增強功能

代碼展示:

配置類

/**
 * @author WGR
 * @create 2019/12/1 -- 20:00
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.topcheer.knife4j.web"))
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8999/")
                .contact("[e-mail]")
                .version("1.0")
                .build();
    }

}

Model層

/**
 * @author WGR
 * @create 2019/12/1 -- 20:02
 */
@ApiModel("通用接口返回對象")
public class Results<T> {

    @ApiModelProperty(required = true,notes = "結果碼",example = "200")
    private int state;
    @ApiModelProperty(required = true,notes = "時間戳",example = "1567425139000")
    private long time;
    @ApiModelProperty(required = true,notes = "返回信息",example = "SUCCESS")
    private String message;
    @ApiModelProperty(required = true,notes = "返回數據",example = "{\"name\":\"blues\"}")
    private T content;

    public Results(int code, String msg, T obj){
        setState(code);
        setMessage(msg);
        setContent(obj);
        setTime(System.currentTimeMillis());
    }


    public int getState() {
        return state;
    }

    public void setState(int state) {
        this.state = state;
    }

    public long getTime() {
        return time;
    }

    public void setTime(long time) {
        this.time = time;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getContent() {
        return content;
    }

    public void setContent(T content) {
        this.content = content;
    }
}


/**
 * @author WGR
 * @create 2019/12/1 -- 20:02
 */
@ApiModel("用戶對象")
public class UserVO {

    @ApiModelProperty(required = true,notes = "用戶名",example = "blues")
    private String name;

    @ApiModelProperty(required = true,notes = "用戶返回消息",example = "hello world")
    private String words;


    public UserVO(String name, String words) {
        this.name = name;
        this.words = words;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getWords() {
        return words;
    }

    public void setWords(String words) {
        this.words = words;
    }
}

Web層

/**
 * @author WGR
 * @create 2019/12/1 -- 20:01
 */
@Api(tags = "HELLO CONTROLLER 測試功能接口")
@RestController
public class HelloController {


    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "用戶名稱",required = true,dataType = "String",paramType = "path",example = "blues")
    })
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "接口返回成功狀態"),
            @ApiResponse(code = 500, message = "接口返回未知錯誤，請聯系開發人員調試")
    })
    @ApiOperation(value = "Hello 測試接口", notes = "訪問此接口，返回hello語句，測試接口")
    @GetMapping("hello/{name}")
    public Results<UserVO> hello(@PathVariable String name){
        UserVO userVO = new UserVO(name,"hello " + name);
        Results<UserVO> results = new Results<>(200,"SUCCESS", userVO);
        return results;
    }

}

pom.xml

<dependencies>
        <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>1.9.6</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>