swagger文档增强工具knife4j使用

swagger安装：

SpringBoot集成Swagger3_springboot集成swing3_生骨大头菜的博客-CSDN博客

使用原生的swagger作为接口文档，功能不够强大，并且默认的ui比较简陋，不符合大众审美。所以实际开发中推荐使用knife4j对swagger进行增强。knife4j的地址：https://gitee.com/xiaoym/knife4j

1.引入knife4j的依赖

        <!--引入knife4j依赖-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

2.搭建springboot环境，创建Controller，用swagger相关注解来描述

package com.example.demo.controller.backstage;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import com.example.demo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;
import java.util.List;

/**
 * 测试控制器
 *
 * @Author: 
 * @Date: 2023/7/4
 * @Description:
 * @Modified By:
 */
@Api(value = "用户", tags = "用户", description = "用户相关的控制器")
@Slf4j
@Data
@RestController
@RequestMapping("demo")
public class DemoController {

    @Resource
    private UserMapper userMapper;

    @Resource
    private UserService userService;

    @ApiOperation("用户-获取")
    @GetMapping("get")
    public String get(@RequestParam(name = "id") Long id) {
        User one = userService.getOne(id);

        System.out.println(one);

        log.info("用户：{}", one);

        return "get";
    }



}

3.此时启动项目，访问ip:端口/doc.html即可看到knife4j的文档界面

4.增强功能

使用knife4j增强功能的前提是要在yaml配置中开启增强模式

knife4j:
  enable: true

5.添加接口作者

swagger只能给整个文档添加作者，不能针对某个接口单独添加作者。knife4j中可以有2种方式给接口添加作者：

• 在Controller类上标注@ApiSupport(author = "作者名称")，这样整个Controller中的所有接口方法将被指定为该作者
• 在Controller接口方法上标注@ApiOperationSupport(author = "作者名称")，这样该接口被指定为该作者

如果@ApiSupport和@ApiOperationSupport同时指定了作者，那么方法级别的@ApiOperationSupport优先级更高

package com.example.demo.controller.backstage;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import com.example.demo.service.UserService;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;
import java.util.List;

/**
 * 测试控制器
 *
 * @Author: 冯健
 * @Date: 2023/7/4
 * @Description:
 * @Modified By:
 */
@Api(value = "用户", tags = "用户", description = "用户相关的控制器")
@Slf4j
@Data
@RestController
@RequestMapping("demo")
@ApiSupport(author = "靓仔")
public class DemoController {

    @Resource
    private UserMapper userMapper;

    @Resource
    private UserService userService;

    @ApiOperationSupport(author = "靓仔")
    @ApiOperation("用户-获取")
    @GetMapping("get")
    public String get(@RequestParam(name = "id") Long id) {
        User one = userService.getOne(id);

        System.out.println(one);

        log.info("用户：{}", one);

        return "get";
    }



}

 

6.生产环境关闭文档

目前Springfox-Swagger以及Knife4j提供的资源接口包括如下：

资源	说明
/doc.html	Knife4j提供的文档访问地址
/v2/api-docs-ext	Knife4j提供的增强接口地址,自2.0.6版本后删除
/swagger-resources	Springfox-Swagger提供的分组接口
/v2/api-docs	Springfox-Swagger提供的分组实例详情接口
/swagger-ui.html	Springfox-Swagger提供的文档访问地址
/swagger-resources/configuration/ui	Springfox-Swagger提供
/swagger-resources/configuration/security	Springfox-Swagger提供

swagger中要实现生产环境关闭文档资源需要在配置类中进行编码，判断环境，比较麻烦。knife4j中只需要在对应环境的配置中添加配置即可

spring:
  profiles: prod # 指定为生产环境
knife4j:
  production: true # 开启屏蔽文档资源

此时只要以prod环境运行，就无法访问到接口文档

注意：如果正常非生产环境下不屏蔽文档，那么引入了springsecurtiy或者自定义拦截器的时候，要排除掉上述表格中的文档资源，否则在非屏蔽状态下也将无法访问到文档资源

7.接口排序

接口排序的方式有2种：

• 针对不同Controller排序：Controller上标注@ApiSupport(order = 序号)
• 针对同一个Controller中的不同方法排序：同一个Controller不同接口方法上标注@ApiOperationSupport(order = 序号)

8.导出离线文档

• markdown：导出当前逻辑分组下所有接口的Markdown格式的文档
• Html：导出当前逻辑分组下所有接口的Html格式的文档
• Word:导出当前逻辑分组下所有接口的Word格式的文档(自2.0.5版本开始)
• OpenAPI:导出当前逻辑分组下的原始OpenAPI的规范json结构(自2.0.6版本开始)
• PDF:未实现

9.过滤请求参数

通常我们在开发接口时,比如一个新增接口和一个修改接口，修改接口需要传递主键id、而新增接口则不需要传递此属性，但大部分情况,我们只写一个Model类,此时在新增接口时显示主键id会显得很多余。使用自定义增强注解@ApiOperationSupport中的ignoreParameters属性，可以强制忽略要显示的参数

10.忽略表单参数

创建一个用户实体类

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.ToString;

import java.io.Serializable;

/**
 * 用户实体类
 *
 * @Author: 
 * @Date: 2023/7/4
 * @Description:
 * @Modified By:
 */
@ToString(callSuper = true)
@EqualsAndHashCode(callSuper = true)
@Data
@TableName("user")
@ApiModel("用户实体")
public class User extends BaseEntity implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("主键")
    private Long id;

    @ApiModelProperty("名称")
    private String name;

    @ApiModelProperty("密码")
    private String password;

}

然后新增一个新增用户的接口方法，用表单方式接收参数，但是忽略掉id。在@ApiOperationSupport中的ignoreParameters属性中填写忽略的属性名称即可

    @PostMapping("user")
    @ApiOperation("用户 - 新增")
    @ApiOperationSupport(ignoreParameters = "id") // 忽略掉User中的id属性，不显示在文档中
    public void addUser(User user) {

    }

注意：

• ignoreParameters支持以数组形式添加多个忽略参数
• ignoreParameters支持忽略级联对象的参数，比如User实体类中有个Address类型的属性addr，那么如果想要忽略Address的属性id，那么只需要配置为ignoreParameters = "addr.id"即可
• 如果要忽略的参数过多，可以使用includeParameters反向配置

11.忽略json参数

如果是以@RequestBody形式接收参数，那么ignoreParameters中填写参数名.要忽略的属性名即

@PostMapping("user")
@ApiOperation("添加用户2")
@ApiOperationSupport(ignoreParameters = {"user.id", "user.age"})
public void addUser2(@RequestBody User user) {

}

注意：

• ignoreParameters支持以数组形式添加多个忽略参数
• ignoreParameters支持忽略级联对象的参数，比如User实体类中有个Address类型的属性addr，那么如果想要忽略Address的属性id，那么只需要配置为ignoreParameters = "user.addr.id"即可
• 如果要忽略的参数过多，可以使用includeParameters反向配置