SpringBoot整合knife4j實踐

更新時間：2025年06月23日 10:02:08 作者：yololee_

這篇文章主要介紹了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:關閉swagger，false:開啟swagger
  production: false
  basic:
    # 是否開啟認證
    enable: false
    # Basic認證用戶名
    username: admin
    # Basic認證密碼
    password: 123456
spring:
  application:
    name: test-knife4j

注解

@Api(tags = {“用戶操作”})
加在controller類上
tags表示該類的標簽，在頁面會獨立顯示一個菜單
 
@ApiOperation(value = “保存用戶”, notes = “保存時，ID由數(shù)據(jù)庫生成，無需填寫，有則忽略”, tags = “保存”)
加在相應的請求處理方法上
value表示該方法的說明
notes相當于對該方法的詳細說明，也就是更加完整的描述
tags 表示標簽，，在頁面會獨立顯示一個菜單
 
@ApiImplicitParam(name = “id”, value = “用戶ID”, defaultValue = “1”)
方法只有一個基本類型參數(shù)時加在方法上。方法有多個參數(shù)時加在@ApiImplicitParams內(nèi)
name 參數(shù)中屬性的名字
value 對這個屬性的描述
defaultValue 默認值，這個還是有必要填寫的，在頁面進行請求時，會自動填充
 
@ApiImplicitParams(value = {})
用在請求方法上
這個注解必須和@ApiImplicitParam配合使用
當請求方法中的請求參數(shù)很多的時候，例如saveUser(String username, Integer age, Date birthday, String phone)
 
@ApiParam(value = “當前頁”, defaultValue = “1”)
加在請求方法的普通參數(shù)上
value的值是對該參數(shù)的說明
與@ApiImplicitParam使用的效果等同，根據(jù)個人喜好進行使用
 
@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 = "復雜傳參")
    @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 = "當前頁", 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 = "刪除后無法恢復")
    @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("刪除用戶");
    }
}

響應參數(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("響應參數(shù)")
@AllArgsConstructor
@NoArgsConstructor
public class ResultVo<T> implements Serializable {

    private static final long serialVersionUID = -8054007511410819665L;

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

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

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


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

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

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

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

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")

如果在方法上使用了注解，并且也在類上使用了注解，那么最后的展示結果以方法上的注解為準

資源屏蔽

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

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

然后重啟項目

訪問頁面加權控制

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

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

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

admin/123321

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

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

接口排序

@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)先級的，也就是說，當同時使用時，只會有一個注解生效，所以在使用的時候需要特別注意。優(yōu)先級規(guī)則如下
@ApiSupport > @ApiSort>@Api

請求參數(shù)緩存

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

Tips:

倆種情況會失效

1、 @ApiModelProperty 注解中添加 example （屬性的示例值）屬性，那么， knife4j 將不會使用緩存，使用的是后端指定的 example
2、當域名發(fā)生改變時，所有緩存將會失效

過濾請求參數(shù)

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

所以，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 = "手機號碼",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 = "詳細地址")
    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

編輯操作

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)試功能,默認值為true(代表開啟調(diào)試)，如果要禁用調(diào)試，該值設為false

同樣，此操作也需要開發(fā)者在創(chuàng)建Docket邏輯分組對象時，通過Knife4j提供的工具對象OpenApiExtensionResolver將擴展屬性進行賦值

禁用搜索框

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

knife4j:
  enable: true
  setting:
    enableSearch: false

enableSearch:該屬性是一個Boolean值，代表是否啟用搜索功能,默認值為true(代表開啟搜索)，如果要禁用搜索，該值設為false

同樣，此操作也需要開發(fā)者在創(chuàng)建Docket邏輯分組對象時，通過Knife4j提供的工具對象OpenApiExtensionResolver將擴展屬性進行賦值。具體的代碼實現(xiàn)請參考禁用調(diào)試和自定義主頁內(nèi)容，我這里就不重復了。

總結

以上為個人經(jīng)驗，希望能給大家一個參考，也希望大家多多支持腳本之家。

您可能感興趣的文章:

Java實現(xiàn)根據(jù)圖片url下載圖片并動態(tài)添加水印
這篇文章主要為大家詳細介紹了如何使用Java實現(xiàn)根據(jù)圖片url下載圖片并動態(tài)添加水印,文中的示例代碼講解詳細,感興趣的小伙伴可以了解下
2026-01-01
Java中反射的20個使用技巧分享
Java反射是一種強大的機制,允許程序在運行時檢查和操作類,接口,字段和方法,本文總結了20個關于Java反射的經(jīng)驗,感興趣的小伙伴可以跟隨小編一起學習一下
2025-05-05
常用的Spring Boot調(diào)用外部接口方式實現(xiàn)數(shù)據(jù)交互
Spring Boot提供了多種調(diào)用外部接口的方式，可以方便地實現(xiàn)與其他系統(tǒng)的數(shù)據(jù)交互，提高系統(tǒng)的可擴展性和數(shù)據(jù)共享能力，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習吧
2023-04-04
SpringBoot中的@Inherited注解詳解
這篇文章主要介紹了SpringBoot中的@Inherited注解詳解,@Inherited是一個標識,用來修飾注解,如果一個類用上了@Inherited修飾的注解,那么其子類也會繼承這個注解,需要的朋友可以參考下
2023-08-08
Java輸出多位小數(shù)的三種方法(附代碼)
這篇文章主要給大家介紹了關于Java輸出多位小數(shù)的三種方法的相關資料,在實際工作中常常需要設定數(shù)字的輸出格式,如以百分比的形式輸出,或者設定小數(shù)位數(shù)等,需要的朋友可以參考下
2023-07-07
java中maven下載和安裝步驟說明
在本篇文章里小編給大家分享的是一篇關于java中maven下載和安裝步驟說明內(nèi)容，對此有興趣的朋友們可以學習參考下。
2021-02-02
Mybatis Plus中的流式查詢案例
這篇文章主要介紹了Mybatis Plus中的流式查詢案例，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
2022-08-08
Spring你不知道的一種解耦模式
本文介紹一種方法，服務定位模式Service?Locator?Pattern來解決，它幫助我們消除緊耦合實現(xiàn)及其依賴性，并提出將服務與其具體類解耦
2023-01-01
SpringMVC中的http Caching的具體使用
本文主要介紹了SpringMVC中的http Caching的具體使用，文中通過示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下
2021-09-09
Java 面試題和答案 - （下）
本文主要介紹Java 面試題，這里整理了Java面試題關于JDBC,線程異常處理，Servlet，JSP的知識的整理，幫助大家理解知識點，便于面試，有興趣的小伙伴可以參考下
2016-09-09