SpringBoot 整合knife4j

這篇具有很好參考價值的文章主要介紹了SpringBoot 整合knife4j。希望對大家有所幫助。如果存在錯誤或未考慮完全的地方，請大家不吝賜教，您也可以點擊"舉報違法"按鈕提交疑問。

Knife4j是一款基于Swagger 2的在線API文檔框架

在Spring Boot中，使用此框架時，需要：

- 添加依賴
- 在配置文件（`application.properties`）中開啟增強模式
- 編寫配置類（代碼相對固定，建議CV）

引入knife4j

添加依賴

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

創(chuàng)建 Swagger 配置依賴

package com.yolo.knife4j.config;

import io.swagger.annotations.Api;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Slf4j
@Configuration
@EnableSwagger2WebMvc
// 對JSR303提供支持
@Import(BeanValidatorPluginsConfiguration.class)
public class Knife4jConfig {

    @Value("${spring.application.name}")
    private String applicationName;
    @Bean
    public Docket defaultApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName(applicationName)
                .select()
                // 添加@Api注解才顯示
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                // 這里指定Controller掃描包路徑
//                .apis(RequestHandlerSelectors.basePackage("com.yolo"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * swagger-api接口描述信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文檔")
                .description("API文檔")
                .contact(
                        new Contact(
                                "yolo",
                                "https://gitee.com/huanglei1111",
                                "2936412130@qq.com"
                        )
                )
                .version("1.0.0")
                .build();
    }
}

application.yml配置文件

# https://doc.xiaominfo.com/knife4j
knife4j:
  # 開啟增強配置
  enable: true
  # 是否開啟生產(chǎn)環(huán)境屏蔽   true:關(guān)閉swagger，false:開啟swagger
  production: false
  basic:
    # 是否開啟認(rèn)證
    enable: false
    # Basic認(rèn)證用戶名
    username: admin
    # Basic認(rèn)證密碼
    password: 123456
spring:
  application:
    name: test-knife4j

注解

@Api(tags = {“用戶操作”})
加在controller類上
tags表示該類的標(biāo)簽，在頁面會獨立顯示一個菜單
 
@ApiOperation(value = “保存用戶”, notes = “保存時，ID由數(shù)據(jù)庫生成，無需填寫，有則忽略”, tags = “保存”)
加在相應(yīng)的請求處理方法上
value表示該方法的說明
notes相當(dāng)于對該方法的詳細(xì)說明，也就是更加完整的描述
tags 表示標(biāo)簽，，在頁面會獨立顯示一個菜單
 
@ApiImplicitParam(name = “id”, value = “用戶ID”, defaultValue = “1”)
方法只有一個基本類型參數(shù)時加在方法上。方法有多個參數(shù)時加在@ApiImplicitParams內(nèi)
name 參數(shù)中屬性的名字
value 對這個屬性的描述
defaultValue 默認(rèn)值，這個還是有必要填寫的，在頁面進(jìn)行請求時，會自動填充
 
@ApiImplicitParams(value = {})
用在請求方法上
這個注解必須和@ApiImplicitParam配合使用
當(dāng)請求方法中的請求參數(shù)很多的時候，例如saveUser(String username, Integer age, Date birthday, String phone)
 
@ApiParam(value = “當(dāng)前頁”, defaultValue = “1”)
加在請求方法的普通參數(shù)上
value的值是對該參數(shù)的說明
與@ApiImplicitParam使用的效果等同，根據(jù)個人喜好進(jìn)行使用
 
@ApiModel(value = “用戶信息”)
加在請求方法的對象類上
value 對該對象參數(shù)的描述
例如有一個請求方法save(UserDTO userDTO), 則需要加在UserDTO這個類上面(可以參照下面的示例)
 
@ApiModelProperty(value = “用戶ID”, example = “1”)
加在請求方法的參數(shù)對象的屬性上
value 對該屬性的描述
example 屬性的示例值，在頁面會自動填充該值
 
 
@ApiIgnore：注解類、參數(shù)、方法，注解后將不在Swagger UI中顯示

案例

package com.yolo.knife4j.controller;

import cn.hutool.core.collection.ListUtil;
import com.yolo.knife4j.base.ResultVo;
import com.yolo.knife4j.dto.UserAddRequest;
import com.yolo.knife4j.vo.StudentVO;
import com.yolo.knife4j.vo.UserVO;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
 
import javax.validation.Valid;
import java.util.Date;

@ApiResponses(value = {
        @ApiResponse(code = 200, message = "接口返回成功狀態(tài)"),
        @ApiResponse(code = 500, message = "接口返回未知錯誤，請聯(lián)系開發(fā)人員調(diào)試")
})
@Api(tags = "用戶")
@RestController
@RequestMapping("/user")
public class UserController {


    @ApiOperation(value = "保存用戶", notes = "簡單傳參")
    @PostMapping("/add")
    public ResultVo<Object> add(@RequestBody @Valid UserAddRequest userAddRequest) {
        return ResultVo.builder().build().setCode(200).setSuccess(true)
                .setTime(new Date()).setMsg("保存用戶成功").setData(userAddRequest);
    }

    @ApiOperation(value = "保存用戶2", notes = "復(fù)雜傳參")
    @PostMapping("/add2")
    public ResultVo<Object> add2(@RequestBody @Valid UserAddRequest userAddRequest) {
        return ResultVo.builder().build().setCode(200).setSuccess(true)
                .setTime(new Date()).setMsg("保存用戶成功").setData(userAddRequest);
    }


    @GetMapping("/list")
    @ApiOperation(value = "查找用戶列表", notes = "根據(jù)id查找單個用戶")
    public ResultVo<Object> list(@RequestParam @ApiParam(value = "當(dāng)前頁", defaultValue = "1") Integer pageNum,
                          @RequestParam @ApiParam(value = "頁大小", defaultValue = "10") Integer pageSize) {

        UserVO vo = new UserVO();
        StudentVO studentVO = StudentVO.builder().build().setAddress("wuhan").setCode(2);
        vo.setStudentVOS(ListUtil.of(studentVO));

        return ResultVo.builder().build().setCode(200).setSuccess(true)
                .setTime(new Date()).setMsg("查找用戶列表").setData(vo);
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "刪除用戶", notes = "刪除后無法恢復(fù)")
    @ApiImplicitParam(name = "id", value = "用戶ID", defaultValue = "1")
    public ResultVo<Object> delete(@PathVariable(name = "id") Long id) {
        return ResultVo.builder().build().setCode(200).setSuccess(true)
                .setTime(new Date()).setMsg("刪除用戶");
    }
}

響應(yīng)參數(shù)

package com.yolo.knife4j.base;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.io.Serializable;
import java.util.Date;

@Data
@Builder
@Accessors(chain = true)
@ApiModel("響應(yīng)參數(shù)")
@AllArgsConstructor
@NoArgsConstructor
public class ResultVo<T> implements Serializable {

    private static final long serialVersionUID = -8054007511410819665L;

    @ApiModelProperty(value = "響應(yīng)狀態(tài)碼", example = "1", dataType = "Integer")
    private int code;

    // 是否成功標(biāo)識.true表示成功,false表示失敗
    @ApiModelProperty("success標(biāo)識,true表示成功,false表示失敗")
    private boolean success;

    // 操作成功時需要響應(yīng)給客戶端的響應(yīng)數(shù)據(jù)
    @ApiModelProperty("響應(yīng)信息")
    private String msg;


    @ApiModelProperty("響應(yīng)數(shù)據(jù)")
    private T data;

    @ApiModelProperty("當(dāng)前時間")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date time;
}

tips: http://127.0.0.1:8080/doc.html

這里端口，就是你運行項目的端口

knife4j-spring-boot-starter,springboot,spring boot,java,spring

knife4j增強功能

springboot 中 knife4j的完整參數(shù)如下：

knife4j:
  enable: true
  documents:
    -
      group: 2.X版本
      name: 接口簽名
      locations: classpath:sign/*
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true
    swaggerModelName: 實體類列表
    enableVersion: false
    enableReloadCacheParameter: false
    enableAfterScript: true
    enableFilterMultipartApiMethodType: POST
    enableFilterMultipartApis: false
    enableRequestCache: true
    enableHost: false
    enableHostText: 192.168.0.193:8000
    enableHomeCustom: true
    homeCustomLocation: classpath:markdown/home.md
    enableSearch: false
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: Apache License 2.0 | Copyright  2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)
    enableDynamicParameter: false
    enableDebug: true
    enableOpenApi: false
    enableGroup: true
  cors: false
  production: false
  basic:
    enable: false
    username: test
    password: 12313

接口添加作者

添加作者有倆種方式

在方法上使用注解 @ApiOperationSupport(author = "yolo-test")
在controller類上使用注解 @ApiSupport(author = "yolo-controller")

如果在方法上使用了注解，并且也在類上使用了注解，那么最后的展示結(jié)果以方法上的注解為準(zhǔn)

knife4j-spring-boot-starter,springboot,spring boot,java,spring

資源屏蔽

當(dāng)我們在生成環(huán)境的時候不想顯示接口文檔，由于 Knife4j 基于 Servlet 體系提供了過濾 Filter 功能，所以就不需要我們再去造輪子了，直接使用即可

knife4j:
  # 開啟增強配置
  enable: true
  # 是否開啟生產(chǎn)環(huán)境屏蔽   true:關(guān)閉swagger，false:開啟swagger
  production: true

然后重啟項目

knife4j-spring-boot-starter,springboot,spring boot,java,spring

訪問頁面加權(quán)控制

針對Swagger的資源接口,Knife4j提供了簡單的Basic認(rèn)證功能

簡單點說，指定一個用戶名和密碼，訪問 Swagger 文檔需要驗證登錄名和密碼，驗證通過之后才能正常訪問

如果用戶開啟了 basic （knife4j.basic.enable = true）認(rèn)證功能，但是沒有指定 username 和password，那么 knife4j 提供了一組默認(rèn)的用戶名密碼

admin/123321

knife4j:
  # 開啟增強配置
  enable: true
  # 是否開啟生產(chǎn)環(huán)境屏蔽   true:關(guān)閉swagger，false:開啟swagger
  production: false
  basic:
    # 是否開啟認(rèn)證
    enable: true
    # Basic認(rèn)證用戶名
    username: admin
    # Basic認(rèn)證密碼
    password: 123456

如果開啟生產(chǎn)環(huán)境屏蔽了，開啟basic認(rèn)證是不生效的

knife4j-spring-boot-starter,springboot,spring boot,java,spring

接口排序

@ApiOperationSupport注解中增加了 order 字段,用于接口排序。在使用此注解之前需要開啟增強功能

分組排序

分組，顧名思義，就是多個 controller 之間的排序，開發(fā)者可以通過注解實現(xiàn)每個controller 之間的排序，實現(xiàn)這個功能的注解一共有三個，具體如下

@ApiSupport

@RestController
@RequestMapping(value = "/test")
@ApiSupport(author = "yolo-controller",order = 999)
@Api(tags = "測試swagger")
public class Knife4jTestController

@ApiSort

@RestController
@RequestMapping(value = "/test")
@ApiSort(value = 999)
@Api(tags = "測試swagger")
public class Knife4jTestController

@Api

@RestController
@RequestMapping(value = "/test")
@Api(tags = "測試swagger",position = 999)
public class Knife4jTestController

Tips:

這三個注解是存在優(yōu)先級的，也就是說，當(dāng)同時使用時，只會有一個注解生效，所以在使用的時候需要特別注意。優(yōu)先級規(guī)則如下

@ApiSupport > @ApiSort>@Api

請求參數(shù)緩存

我們在調(diào)試接口的時候，有的接口會有很多參數(shù)，當(dāng)我們好不容易填好了所有的參數(shù)，由于我們不小心關(guān)閉了頁面，下次再調(diào)試的時候發(fā)現(xiàn)還需要再次將參數(shù)輸入一遍，心態(tài)會爆炸吧，所以 knife4j 在文檔管理中增加了一個選項：開啟請求參數(shù)緩存

knife4j-spring-boot-starter,springboot,spring boot,java,spring

Tips:

倆種情況會失效

1、 @ApiModelProperty 注解中添加 example （屬性的示例值）屬性，那么， knife4j 將不會使用緩存，使用的是后端指定的 example

2、當(dāng)域名發(fā)生改變時，所有緩存將會失效

過濾請求參數(shù)

我們在開發(fā)過程中，經(jīng)常會遇到這樣的一個問題，新增和修改接口，修改接口需要傳遞修改的記錄id，但是新增則不需要，而后端往往會將修改和新增的入?yún)ο笤O(shè)置為一個對象，那么這個對象中必然會存在 id 字段，這就會對新增造成誤導(dǎo)

所以，knife4j 支持了請求參數(shù)的過濾（忽略），實現(xiàn)方式也是非常的簡單，使用自定義增強注解ApiOperationSupport中的ignoreParameters屬性,可以強制忽略要顯示的參數(shù)

這里表單和json格式過濾參數(shù)是不一樣的

我們先看表單格式

@ApiModel("用戶信息")
@Getter
@Setter
@ToString
public class UserDTO {
    @ApiModelProperty(value = "用戶id")
    private Long id;
    @ApiModelProperty(value = "用戶名",example = "李雷")
    private String username;
    @ApiModelProperty(value = "性別",example = "男")
    private String gender;
    @ApiModelProperty(value = "手機(jī)號碼",example = "18888888888")
    private String phone;
    @ApiModelProperty(value = "用戶收貨地址信息")
    private UserAddressDTO userAddressDTO;
}

@Getter
@Setter
@ToString
public class UserAddressDTO {
    @ApiModelProperty(value = "收獲地址的記錄id")
    private Long id;
    
    @ApiModelProperty(value = "省")
    private String province;
    @ApiModelProperty(value = "市")
    private String city;
    @ApiModelProperty(value = "區(qū)")
    private String district;
    @ApiModelProperty(value = "詳細(xì)地址")
    private String addr;
}



    @PostMapping(value = "/saveUser")
    @ApiOperation("新增用戶信息-表單")
    @ApiOperationSupport(author = "yolo",ignoreParameters = {"id","userAddressDTO.id"})
    public String saveUser(UserDTO userDTO){
        System.out.println("前端傳遞的用戶信息："+ userDTO);
        return "save success";
    }
    @PostMapping(value = "/updateUser")
    @ApiOperation("編輯用戶信息")
    @ApiOperationSupport(author = "yolo")
    public String updateUser( UserDTO userDTO){
        System.out.println("前端傳遞的用戶信息："+ userDTO);
        return "edit success";
    }

在過濾字段的時候，第一層我們只要填寫對象中的屬性名即可，但如果需要過濾第二層，根據(jù)忽略規(guī)則中的第二條，我們在 UserDTO 對象中引入 UserAddressDTO 對象：private UserAddressDTO userAddressDTO; 我們還需要忽略 UserAddressDTO 對象中的 id 屬性，那么需要填上 userAddressDTO.id ，其中 userAddressDTO 要與 UserDTO 對象中的 UserAddressDTO 屬性名一致

新增操作沒有id

knife4j-spring-boot-starter,springboot,spring boot,java,spring

編輯操作

knife4j-spring-boot-starter,springboot,spring boot,java,spring

JSON格式忽略

專業(yè)說法是：實例名.屬性名，以新增用戶為例，我們需要過濾用戶id，那么寫法就是：userDTO.id，其中 userDTO 為 saveUser() 的參數(shù)名

    @PostMapping(value = "/saveUser")
    @ApiOperation("新增用戶信息")
    @ApiOperationSupport(author = "yolo",ignoreParameters = {"userDTO.id","userDTO.userAddressDTO.id"})
    public String saveUser(@RequestBody UserDTO userDTO){
        System.out.println("前端傳遞的用戶信息："+ userDTO);
        return "save success";
    }

禁用調(diào)試

knife4j:
  enable: true
  setting:
    enableDebug: false

enableDebug:該屬性是一個Boolean值，代表是否啟用調(diào)試功能,默認(rèn)值為true(代表開啟調(diào)試)，如果要禁用調(diào)試，該值設(shè)為false
同樣，此操作也需要開發(fā)者在創(chuàng)建Docket邏輯分組對象時，通過Knife4j提供的工具對象OpenApiExtensionResolver將擴(kuò)展屬性進(jìn)行賦值

knife4j-spring-boot-starter,springboot,spring boot,java,spring

禁用搜索框

發(fā)者如果想要禁用Ui界面中的搜索功能，需要通過增強屬性進(jìn)行配置，此功能需要開啟增強功能

knife4j:
  enable: true
  setting:
    enableSearch: false

enableSearch:該屬性是一個Boolean值，代表是否啟用搜索功能,默認(rèn)值為true(代表開啟搜索)，如果要禁用搜索，該值設(shè)為false
同樣，此操作也需要開發(fā)者在創(chuàng)建Docket邏輯分組對象時，通過Knife4j提供的工具對象OpenApiExtensionResolver將擴(kuò)展屬性進(jìn)行賦值。具體的代碼實現(xiàn)請參考禁用調(diào)試和自定義主頁內(nèi)容，我這里就不重復(fù)了。文章來源地址http://www.zghlxwxcb.cn/news/detail-628342.html

到了這里，關(guān)于SpringBoot 整合knife4j的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！