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

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

一、引入依賴

Knife4J 官網(wǎng)：

https://doc.xiaominfo.com/

快速開始：https://doc.xiaominfo.com/docs/quick-start

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

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

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

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

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

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

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

三、常用注解

3-1 @Api

@Api 注解，添加在 Controller 類上，標記它作為 Swagger 文檔資源。

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

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

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

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

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

3-2 @ApiOperation

@ApiOperation 注解，添加在 Controller 方法上，標記它是一個 API 操作。

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

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

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

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

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

3-3 @ApiImplicitParam

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

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

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

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

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

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

• defaultValue 屬性：默認值。
• allowableValues 屬性：允許的值。如果要設置多個值，有兩種方式：

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

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

當我們需要添加在方法上添加多個 @ApiImplicitParam 注解時，可以使用 @ApiImplicitParams 注解中添加多個。

3-4 @ApiModel

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

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

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

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

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

3-5 @ApiModelProperty

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

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

• value 屬性：屬性的描述。
• dataType 屬性：和 @ApiImplicitParam 注解的 dataType 屬性一致。不過因為 @ApiModelProperty 是添加在成員變量上，可以自動獲得成員變量的類型。
• required 屬性：和 @ApiImplicitParam 注解的 required 屬性一致。
• example 屬性：@ApiImplicitParam 注解的 example 屬性一致。

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

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

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

3-6 @ApiResponse

在大多數(shù)情況下，我們并不需要使用 @ApiResponse 注解，因為我們會類似 UserController#get(id) 方法這個接口，返回一個 Model 即可。

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

當我們需要添加在方法上添加多個 @ApiResponse 注解時，可以使用 @ApiResponses 注解中添加多個。

四、配置JavaBean

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

@Getter
@Setter
@ToString
@NoArgsConstructor
@ApiModel(value = "輪播圖對象", 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 = "標題", example = "這是一個標題喲~")
    private String title;
}

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

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

@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public abstract class RBean {
    @ApiModelProperty(value = "響應碼",
            position = 0,
            example = "200",
            notes = "200: 成功；500：失??；")
    private Integer code;
    @ApiModelProperty(value = "響應說明", 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ù)項", 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

潦草的寫幾個接口

@Api(tags = "首頁模塊")
@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("查詢一個具體輪播圖")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "title",value = "標題",required = true,example = "小白菜"),
            @ApiImplicitParam(name = "date",value = "時間",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;
    }
}

六、接口文檔預覽

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

最新評論