一、介紹

Knife4j【快速開(kāi)始】是為Java MVC框架集成Swagger生成API文檔的增強(qiáng)解決方案（在非Java項(xiàng)目中也提供了前端UI的增強(qiáng)解決方案），前身是Swagger2，取名Knife4j是希望她能像一把匕首一樣小巧、輕量，并且功能強(qiáng)悍。

Knife4j

二、開(kāi)源倉(cāng)庫(kù)

• Github

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

• 碼云

https://gitee.com/xiaoym/knife4j

三、功能特性

• 簡(jiǎn)潔
  基于左右菜單式的布局方式，更符合國(guó)人的操作習(xí)慣，文檔更清晰
• 個(gè)性化配置
  支持接口地址、接口description屬性、UI增強(qiáng)等個(gè)性化配置
• 增強(qiáng)
  接口排序、Swagger資源保護(hù)、導(dǎo)出Markdown、參數(shù)緩存等眾多強(qiáng)大功能

核心功能

該UI增強(qiáng)包主要包括兩大核心功能：文檔說(shuō)明 和 在線調(diào)試

• 文檔說(shuō)明：根據(jù)Swagger的規(guī)范說(shuō)明，詳細(xì)列出接口文檔的說(shuō)明，包括接口地址、類(lèi)型、請(qǐng)求示例、請(qǐng)求參數(shù)、響應(yīng)示例、響應(yīng)參數(shù)、響應(yīng)碼等信息，使用swagger-bootstrap-ui能根據(jù)該文檔說(shuō)明，對(duì)該接口的使用情況一目了然
• 在線調(diào)試：提供在線接口聯(lián)調(diào)的強(qiáng)大功能，自動(dòng)解析當(dāng)前接口參數(shù)，同時(shí)包含表單驗(yàn)證，調(diào)用參數(shù)可返回接口響應(yīng)內(nèi)容、Header、Curl請(qǐng)求命令實(shí)例、響應(yīng)時(shí)間、響應(yīng)狀態(tài)碼等信息，幫助開(kāi)發(fā)者在線調(diào)試，而不必通過(guò)其他測(cè)試工具測(cè)試接口是否正確，簡(jiǎn)潔、強(qiáng)大。

UI增強(qiáng)

同時(shí)，swagger-bootstrap-ui在滿足以上功能的同時(shí)，還提供了文檔的增強(qiáng)功能，每一個(gè)增強(qiáng)的功能都是貼合實(shí)際，考慮到開(kāi)發(fā)者的實(shí)際開(kāi)發(fā)需要，是必不可少的功能，主要包括：

• 個(gè)性化配置：通過(guò)個(gè)性化UI配置項(xiàng)，可自定義UI的相關(guān)顯示信息
• 離線文檔：Knife4j提供導(dǎo)出4種格式的離線文檔（HTML、Markdown、Word、PDF）
• 接口排序：自1.8.5后，UI支持了接口排序功能，例如一個(gè)注冊(cè)功能包含了多個(gè)步驟，可以根據(jù)swagger-bootstrap-ui提供的接口排序規(guī)則實(shí)現(xiàn)接口的排序，步驟化接口操作，方便其他開(kāi)發(fā)者進(jìn)行接口對(duì)接
• 全局搜索：搜索關(guān)鍵字主要包括：URL地址、接口說(shuō)明、方法類(lèi)型、接口描述

四、功能預(yù)覽

• pom.xml

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

• Swagger2Config

package game.leif.fantasy_all_star;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("game.leif.fantasy_all_star.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Fantasy All Star - 接口文檔")
                .description("本項(xiàng)目模擬了回合制對(duì)戰(zhàn)類(lèi)游戲，讓玩家能夠體驗(yàn)到來(lái)自不同游戲、動(dòng)漫、影視、小說(shuō)中的經(jīng)典人物互相組隊(duì)對(duì)戰(zhàn)的暢爽快感。")
                .contact(new Contact("Leif Liu", null, "leif1995@dingtalk.com"))
                .version("v1.0.0")
                .build();
    }
}

• filter

filterURLSet.add("/swagger-resources");
filterURLSet.add("/v2/api-docs");
filterURLSet.add("/v2/api-docs-ext");

#Knife4j
location ^~ /knife4j {
    proxy_pass http://192.168.2.192:20300/api/doc.html;
}
location ^~ /webjars/ {
    proxy_pass http://192.168.2.192:20300/api/webjars/;
}
location ^~ /swagger-resources {
    proxy_pass http://192.168.2.192:20300/api/swagger-resources;
}
location ^~ /v2/api-docs {
    proxy_pass http://192.168.2.192:20300/api/v2/api-docs;
}

• Controller

@Api(value = "用戶", tags = {"用戶"})

@ApiOperation(value = "登陸接口", notes = "用于用戶登陸")
@ApiImplicitParams({
        @ApiImplicitParam(name = "response", value = "參數(shù)用例", required = false, dataType = DataTypeConstants.STRING, paramType = RequestTypeConstants.QUERY)
})
@ApiResponses({
        @ApiResponse(code = 1, message = "自定義響應(yīng)狀態(tài)碼")
})
@ApiOperationSupport(order = 1, params = @DynamicParameters(name = "CreateOrderModel",properties = {
        @DynamicParameter(name = "id",value = "注解id",example = "X000111",required = true,dataTypeClass = Integer.class),
        @DynamicParameter(name = "name",value = "訂單編號(hào)",required = false)
}), responses = @DynamicResponseParameters(properties = {
        @DynamicParameter(name = "result", value = "返回結(jié)果", dataTypeClass = String.class)
}))

• View Object

@ApiModel(description = "登陸表單")

@ApiModelProperty(value = "用戶名", required = true, example = "leif", position = 1)

• application.yml

# 是否停用Knife4j文檔
knife4j:
  production: false

接口文檔

在線調(diào)試

全局參數(shù)設(shè)置

離線文檔

個(gè)性化設(shè)置