使用knife4j後，終於放棄了swagger-ui

介紹

knife4j是爲Java MVC框架集成Swagger生成Api文檔的增強解決方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一樣小巧,輕量,並且功能強悍!

knife4j的前身是swagger-bootstrap-ui，爲了契合微服務的架構發展,由於原來swagger-bootstrap-ui採用的是後端Java代碼+前端Ui混合打包的方式,在微服務架構下顯的很臃腫,因此項目正式更名爲knife4j。

目前項目主要的模塊如下：

此示例根據官方文檔介紹演示。

開源倉庫

Github

https://github.com/xiaoymin/swagger-bootstrap-ui

碼雲

https://gitee.com/xiaoym/knife4j

核心功能

該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化接口操作，方便其他開發者進行接口對接

功能預覽

在線預覽

http://knife4j.xiaominfo.com/doc.html

快速開始

相信使用過springboot的人大都知道和用過swagger，knife4j的使用方法和swagger幾乎一模一樣，沒有什麼學習成本，不同的是展示的接口UI文檔更加友好和人性化。下面開始演示一個集成項目，首先來看pom文件依賴：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>1.9.6</version>
</dependency>

只引入一個knife4j的starter即可，不用其它依賴。springboot的配置文件和啓動類不用做任何特殊配置，使用knife4j需要一個swagger的配置類，這個配置類和以前使用swagger幾乎是一樣的：

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("spring.boot.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("項目接口文檔")
                .description("服務相關接口")
                .contact(new Contact("vincent",null,"[email protected]"))
                .version("1.0")
                .build();
    }

}

可以看到，內容上沒什麼變化，唯一的變化是類註解需要比原來的swagger多加一個 @EnableSwaggerBootstrapUi。這樣knife4j的所有配置都完成了，啓動項目可以訪問地址：

http://localhost:8080/doc.html?plus=1

來看一下效果：

接口配置

下面來配置一個簡單的接口，查看文檔的展示效果。

首先來看接口的通用返回結果：

@ApiModel("通用接口返回對象")
@AllArgsConstructor
@NoArgsConstructor
@Data
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;

}

@ApiModel("用戶對象")
@AllArgsConstructor
@NoArgsConstructor
@Data
public class UserVO {

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

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

  
}

通過上面兩個的定義，接口的返回類型就搞定了，下面來看接口：

@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;
    }

}

這個接口類中分爲幾個部分需要注意，第一是類上面的@Api註解，描述了整個類的接口分類含義。還有一個是每個接口上面的 @ApiImplicitParams 註解，定義了接口的所有參數。還有@ApiResponses註解，定義了返回時，所有狀態碼所代表的的含義，最後是@ApiOperation註解，描述了單個接口本身的功能。

定義接口完成後，我們來重啓項目，查看文檔的效果：