knife4j是為Java MVC框架集成Swagger生成Api文檔的增強(qiáng)解決方案。

knife4j的前身是swagger-bootstrap-ui，為了契合微服務(wù)的架構(gòu)發(fā)展，由于原來(lái)swagger-bootstrap-ui采用的是后端Java代碼+前端Ui混合打包的方式,在微服務(wù)架構(gòu)下顯的很臃腫，因此項(xiàng)目正式更名為knife4j。 knife4j官方網(wǎng)址：knife4j

一、引入依賴(lài)

Knife4J 官網(wǎng)：

https://doc.xiaominfo.com/

快速開(kāi)始：https://doc.xiaominfo.com/docs/quick-start

<!--引入Knife4j的官方start包,Swagger2基于Springfox2.10.5項(xiàng)目-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <!--使用Swagger2-->
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

二、創(chuàng)建配置類(lèi)

創(chuàng)建config包，在其中新建一個(gè)配置類(lèi)：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2規(guī)范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //描述字段支持Markdown語(yǔ)法
                .description("# 寫(xiě)一個(gè)簡(jiǎn)要的描述")
                .termsOfServiceUrl("https://doc.xiaominfo.com/")
                .contact("可以寫(xiě)作者的信息")
                .version("1.0")
                .build())
                //分組名稱(chēng)
                .groupName("用戶(hù)服務(wù)")
                .select()
                //這里指定Controller掃描包路徑
                .apis(RequestHandlerSelectors.basePackage("com.xueou.boot.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

• 最重要的配置還是：指定
• Controller掃描包路徑contact

官方是棄用了直接傳字符串的這個(gè)設(shè)置方法，改用傳入一個(gè)Contact類(lèi)，看一下源碼可以發(fā)現(xiàn)該類(lèi)的結(jié)構(gòu)（內(nèi)容更豐富了：姓名、郵箱、URL連接）

三、常用注解

3-1 @Api

@Api 注解，添加在 Controller 類(lèi)上，標(biāo)記它作為 Swagger 文檔資源。

3-1-1 @Api 注解的常用屬性，如下：

• tags 屬性：用于控制 API 所屬的標(biāo)簽列表。[] 數(shù)組，可以填寫(xiě)多個(gè)。
• 可以在一個(gè) Controller 上的 @Api 的 tags 屬性，設(shè)置多個(gè)標(biāo)簽，那么這個(gè) Controller 下的 API 接口，就會(huì)出現(xiàn)在這兩個(gè)標(biāo)簽中。
• 如果在多個(gè) Controller 上的 @Api 的 tags 屬性，設(shè)置一個(gè)標(biāo)簽，那么這些 Controller 下的 API 接口，僅會(huì)出現(xiàn)在這一個(gè)標(biāo)簽中。
• 本質(zhì)上，tags 就是為了分組 API 接口，和 Controller 本質(zhì)上是一個(gè)目的。所以絕大數(shù)場(chǎng)景下，我們只會(huì)給一個(gè) Controller 一個(gè)唯一的標(biāo)簽。

3-1-2 @Api 注解的不常用屬性，如下：

• produces 屬性：請(qǐng)求請(qǐng)求頭的可接受類(lèi)型( Accept )。如果有多個(gè)，使用 , 分隔。
• consumes 屬性：請(qǐng)求請(qǐng)求頭的提交內(nèi)容類(lèi)型( Content-Type )。如果有多個(gè)，使用 , 分隔。
• protocols 屬性：協(xié)議，可選值為 “http”、“https”、“ws”、“wss” 。如果有多個(gè)，使用 , 分隔。
• authorizations 屬性：授權(quán)相關(guān)的配置，[] 數(shù)組，使用 @Authorization 注解。hidden 屬性：是否隱藏，不再 API 接口文檔中顯示。

@Api 注解的廢棄屬性，不建議使用，有 value、description、basePath、position 。

3-2 @ApiOperation

@ApiOperation 注解，添加在 Controller 方法上，標(biāo)記它是一個(gè) API 操作。

3-2-1 @ApiOperation 注解的常用屬性，如下：

• value 屬性：API 操作名。
• notes 屬性：API 操作的描述。

3-2-2 @ApiOperation 注解的不常用屬性，如下：

• tags 屬性：和 @API 注解的 tags 屬性一致。
• nickname 屬性：API 操作接口的唯一標(biāo)識(shí)，主要用于和第三方工具做對(duì)接。
• httpMethod 屬性：請(qǐng)求方法，可選值為 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH 。因?yàn)?Swagger 會(huì)解析 SpringMVC 的注解，所以一般無(wú)需填寫(xiě)。
• produces 屬性：和 @API 注解的 produces 屬性一致。
• consumes 屬性：和 @API 注解的 consumes 屬性一致。
• protocols 屬性：和 @API 注解的 protocols 屬性一致。
• authorizations 屬性：和 @API 注解的 authorizations 屬性一致。
• hidden 屬性：和 @API 注解的 hidden 屬性一致。
• response 屬性：響應(yīng)結(jié)果類(lèi)型。因?yàn)?Swagger 會(huì)解析方法的返回類(lèi)型，所以一般無(wú)需填寫(xiě)。
• responseContainer 屬性：響應(yīng)結(jié)果的容器，可選值為 List、Set、Map 。
• responseReference 屬性：指定對(duì)響應(yīng)類(lèi)型的引用。這個(gè)引用可以是本地，也可以是遠(yuǎn)程。并且，當(dāng)設(shè)置了它時(shí)，會(huì)覆蓋 response 屬性。說(shuō)人話(huà)，就是可以忽略這個(gè)屬性，哈哈哈。responseHeaders 屬性：響應(yīng)頭，[] 數(shù)組，使用 @ResponseHeader 注解。
• code 屬性：響應(yīng)狀態(tài)碼，默認(rèn)為 200 。
• extensions 屬性：拓展屬性，[] 屬性，使用 @Extension 注解。
• ignoreJsonView 屬性：在解析操作和類(lèi)型，忽略 JsonView 注釋。主要是為了向后兼容。

@ApiOperation 注解的廢棄屬性，不建議使用，有 position 。

3-3 @ApiImplicitParam

@ApiImplicitParam 注解，添加在 Controller 方法上，聲明每個(gè)請(qǐng)求參數(shù)的信息。

3-3-1 @ApiImplicitParam 注解的常用屬性，如下：

• name 屬性：參數(shù)名。
• value 屬性：參數(shù)的簡(jiǎn)要說(shuō)明。
• required 屬性：是否為必傳參數(shù)。默認(rèn)為 false 。
• dataType 屬性：數(shù)據(jù)類(lèi)型，通過(guò)字符串 String 定義。
• dataTypeClass 屬性：數(shù)據(jù)類(lèi)型，通過(guò) dataTypeClass 定義。在設(shè)置了dataTypeClass 屬性的情況下，會(huì)覆蓋 dataType 屬性。推薦采用這個(gè)方式。
• paramType 屬性：參數(shù)所在位置的類(lèi)型。有如下 5 種方式：

"path" 值：對(duì)應(yīng) SpringMVC 的 @PathVariable 注解。
【默認(rèn)值】"query" 值：對(duì)應(yīng) SpringMVC 的 @PathVariable 注解。
"body" 值：對(duì)應(yīng) SpringMVC 的 @RequestBody 注解。
"header" 值：對(duì)應(yīng) SpringMVC 的 @RequestHeader 注解。
"form" 值：Form 表單提交，對(duì)應(yīng) SpringMVC 的 @PathVariable 注解。
絕大多數(shù)情況下，使用 “query” 值這個(gè)類(lèi)型即可。

• example 屬性：參數(shù)值的簡(jiǎn)單示例。
• examples 屬性：參數(shù)值的復(fù)雜示例，使用 @Example 注解。

3-3-2 @ApiImplicitParam 注解的不常用屬性，如下：

• defaultValue 屬性：默認(rèn)值。
• allowableValues 屬性：允許的值。如果要設(shè)置多個(gè)值，有兩種方式：

數(shù)組方式，即 {value1, value2, value3} 。例如說(shuō)，{1, 2, 3} 。
范圍方式，即 [value1, value2] 或 [value1, value2) 。例如說(shuō) [1, 5] 表示 1 到 5 的所有數(shù)字。如果有無(wú)窮的，可以使用 (-infinity, value2] 或 [value1, infinity) 。

• allowEmptyValue 屬性：是否允許空值。
• allowMultiple 屬性：是否允許通過(guò)多次傳遞該參數(shù)來(lái)接受多個(gè)值。默認(rèn)為 false 。
• type 屬性：搞不懂具體用途，對(duì)應(yīng)英文注釋為 Adds the ability to override the detected type 。
• readOnly 屬性：是否只讀。
• format 屬性：自定義的格式化。
• collectionFormat 屬性：針對(duì) Collection 集合的，自定義的格式化。

當(dāng)我們需要添加在方法上添加多個(gè) @ApiImplicitParam 注解時(shí)，可以使用 @ApiImplicitParams 注解中添加多個(gè)。

3-4 @ApiModel

@ApiModel 注解，添加在 POJO 類(lèi)，聲明 POJO 類(lèi)的信息。而在 Swagger 中，把這種 POJO 類(lèi)稱(chēng)為 Model 類(lèi)。所以，我們下文就統(tǒng)一這么稱(chēng)呼。

3-4-1 @ApiModel 注解的常用屬性，如下：

• value 屬性：Model 名字。
• description 屬性：Model 描述。

3-4-2 @ApiModel 注解的不常用屬性，如下：

• parent 屬性：指定該 Model 的父 Class 類(lèi)，用于繼承父 Class 的 Swagger 信息。
• subTypes 屬性：定義該 Model 類(lèi)的子類(lèi) Class 們。
• discriminator 屬性：搞不懂具體用途，對(duì)應(yīng)英文注釋為 Supports model inheritance and polymorphism.
• reference 屬性：搞不懂具體用途，對(duì)應(yīng)英文注釋為 Specifies a reference to the corresponding type definition, overrides any other metadata specified

3-5 @ApiModelProperty

• @ApiModelProperty 注解，添加在 Model 類(lèi)的成員變量上，聲明每個(gè)成員變量的信息。

3-5-1 @ApiModelProperty 注解的常用屬性，如下：

• value 屬性：屬性的描述。
• dataType 屬性：和 @ApiImplicitParam 注解的 dataType 屬性一致。不過(guò)因?yàn)?@ApiModelProperty 是添加在成員變量上，可以自動(dòng)獲得成員變量的類(lèi)型。
• required 屬性：和 @ApiImplicitParam 注解的 required 屬性一致。
• example 屬性：@ApiImplicitParam 注解的 example 屬性一致。

3-5-2 @ApiModelProperty 注解的不常用屬性，如下：

• name 屬性：覆蓋成員變量的名字，使用該屬性進(jìn)行自定義。
• allowableValues 屬性：和 @ApiImplicitParam 注解的 allowableValues 屬性一致。
• position 屬性：成員變量排序位置，默認(rèn)為 0 。
• hidden 屬性：@ApiImplicitParam 注解的 hidden 屬性一致。
• accessMode 屬性：訪(fǎng)問(wèn)模式，有 AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE 三種，默認(rèn)為 AccessMode.AUTO 。
• reference 屬性：和 @ApiModel 注解的 reference 屬性一致。
• allowEmptyValue 屬性：和 @ApiImplicitParam 注解的 allowEmptyValue 屬性一致。
• extensions 屬性：和 @ApiImplicitParam 注解的 extensions 屬性一致。

@ApiModelProperty 注解的廢棄屬性，不建議使用，有 readOnly 。

3-6 @ApiResponse

在大多數(shù)情況下，我們并不需要使用 @ApiResponse 注解，因?yàn)槲覀儠?huì)類(lèi)似 UserController#get(id) 方法這個(gè)接口，返回一個(gè) Model 即可。

• @ApiResponse 注解，添加在 Controller 類(lèi)的方法上，聲明每個(gè)響應(yīng)參數(shù)的信息。
• @ApiResponse 注解的屬性，基本已經(jīng)被 @ApiOperation 注解所覆蓋，如下：
• message 屬性：響應(yīng)的提示內(nèi)容。
• code 屬性：和 @ApiOperation 注解的 code 屬性一致。
• response 屬性：和 @ApiOperation 注解的 response 屬性一致。
• reference 屬性：和 @ApiOperation 注解的 responseReference 屬性一致。
• responseHeaders 屬性：和 @ApiOperation 注解的 responseHeaders 屬性一致。
• responseContainer 屬性：和 @ApiOperation 注解的 responseContainer 屬性一致。
• examples 屬性：和 @ApiOperation 注解的 examples 屬性一致。

當(dāng)我們需要添加在方法上添加多個(gè) @ApiResponse 注解時(shí)，可以使用 @ApiResponses 注解中添加多個(gè)。

四、配置JavaBean

主要用于返回參數(shù)、或是接收參數(shù)的時(shí)候進(jìn)行說(shuō)明。

@Getter
@Setter
@ToString
@NoArgsConstructor
@ApiModel(value = "輪播圖對(duì)象", description = "")
public class Banner implements Serializable {
    @ApiModelProperty(value = "id", example = "1")
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;
    @ApiModelProperty(value = "圖像鏈接", example = "https://xxx/xxx.png")
    private String imgUrl;
    @ApiModelProperty(value = "標(biāo)題", example = "這是一個(gè)標(biāo)題喲~")
    private String title;
}

我自己用的時(shí)候，又封裝了一層，設(shè)置了幾個(gè)JavaBean用于包裝返回的響應(yīng)結(jié)果：

分別用于返回單個(gè)數(shù)據(jù)、數(shù)據(jù)列表，同時(shí)附帶上狀態(tài)碼和說(shuō)明信息。

@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public abstract class RBean {
    @ApiModelProperty(value = "響應(yīng)碼",
            position = 0,
            example = "200",
            notes = "200: 成功；500：失??；")
    private Integer code;
    @ApiModelProperty(value = "響應(yīng)說(shuō)明", position = 1, example = "xx數(shù)據(jù)獲取成功。")
    private String msg;
}

// =====================
@EqualsAndHashCode(callSuper=true)
@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class ROneBean<T> extends RBean {

    @ApiModelProperty(value = "數(shù)據(jù)項(xiàng)", position = 2)
    private T data;
}

// =======================
@EqualsAndHashCode(callSuper=true)
@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class RListBean<T> extends RBean{
    @ApiModelProperty(value = "數(shù)據(jù)列表", position = 2)
    private List<T> data;
}

五、配置Controller

潦草的寫(xiě)幾個(gè)接口

@Api(tags = "首頁(yè)模塊")
@RestController
public class IndexController {
    @Resource
    IBannerService iBannerService;

    @ApiOperation(value = "域名直接轉(zhuǎn)接口文檔", hidden = true)
    @GetMapping("/")
    public void toDoc(HttpServletResponse response) throws IOException {
        response.sendRedirect("/doc.html");
    }
    
    @ApiOperation("新增輪播圖數(shù)據(jù)")
    @PostMapping("/addBanners")
    public void putBanner(@RequestBody Banner banner){
		// ......
    }
    
    @ApiOperation("查詢(xún)一個(gè)具體輪播圖")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "title",value = "標(biāo)題",required = true,example = "小白菜"),
            @ApiImplicitParam(name = "date",value = "時(shí)間",required = true,example = "2022")
    })
    @GetMapping("/searchOneBanner")
    public ROneBean<Banner> searchOneBanner(@RequestParam(name = "title",defaultValue = "") String name,
                                           @RequestParam(name = "date", defaultValue = "") String address){
        ROneBean<Banner> resp = new ROneBean<>();
        // ...
        return null
    }

    @ApiOperation("獲取輪播圖數(shù)據(jù)")
    @GetMapping("/getBanners")
    public RListBean<Banner> getBanners(){
        RListBean<Banner> resp = new RListBean<>();
        List<Banner> banners = iBannerService.list();
        if(banners.isEmpty()){
            resp.setCode(200);
            resp.setMsg("輪播圖數(shù)據(jù)為空。");
        }else{
            resp.setCode(200);
            resp.setMsg("獲取輪播圖數(shù)據(jù)成功");
            resp.setData(banners);
        }
        return resp;
    }
}

六、接口文檔預(yù)覽

到此這篇關(guān)于SpringBoot中使用Knife4J的文章就介紹到這了,更多相關(guān)SpringBoot 使用Knife4J內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論