SpringBoot整合Knife4j替代Swagger

文章目录

一、前言
二、正文
- 1. 基础环境
- 2. 引入依赖
- 3. 配置类—Knife4jConfig类
- 4. 各配置项分别演示
- 5. 完整代码
三、总结

一、前言

昨天收到一条评论，让我觉得有些小事应该坚持做下去。

SpringBoot前后端分离项目中，一般会借助Swagger生成API文档，相信在日常的开发中，同学们已经应用的比较熟练。但是，在使用过程中，肯定也会发现Swagger中有很多的不方便之处，这些缺点一直饱受诟病，于是在17年，knife4j横空出世。当然一开始它也只是一个swagger的UI皮肤，随着时间的推移，knife4j已经迭代了很多的版本，支持者也不断增加。如果你的项目仍然在使用swagger，那么就跟随笔者的这篇博文，一起领略下knife4j的强大之处吧。官网：knife4j

本文基于上一篇，SpringBoot整合新版本Mybatis-Plus代码生成器所生成的项目进行测试演示。

二、正文 1. 基础环境

SpringBoot版本：>= 2.2.x
knife4j：2.0.7

特别注意
1、目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。另外在网关层聚合(例如gateway)时，必须禁用Knife4j的增强模式
2、使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

再啰嗦一句，我翻了翻官网，官网说：需要注意的是，目前Knife4j的主版本依然是沿用2.x的版本号，也就是从2.0.6版本开始逐步升级，迭代发布时版本会随之升级，但同时3.x版本也会同步更新发布，主要是满足开发者对于springfox3以及OpenAPI3规范的使用。

因此，本文依然以2.0.6之后的版本进行各配置演示。

2. 引入依赖


    com.github.xiaoymin
    knife4j-spring-boot-starter
    2.0.7

3. 配置类—Knife4jConfig类

package com.ieslab.knife4j.demo.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.documentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("演示Knife4j接口文档")
                        .description("@是小宗啊？")
                        .termsOfServiceUrl("http://localhost:8088/api
@Getter
@Setter
@TableName("user")
@ApiModel(value = "User对象", description = "")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "用户ID" ,example = "1")
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @ApiModelProperty(value = "时间" ,example = "2021-11-05 12:04:00")
    @TableField("time")
    private LocalDateTime time;

    @ApiModelProperty(value = "用户名称" ,example = "小宗")
    @TableField("name")
    private String name;

    @ApiModelProperty(value = "用户内容" ,example = "这里是用户内容。")
    @TableField("content")
    private String content;


}

UserController类：

package com.ieslab.knife4j.demo.module.student.controller;


import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import com.ieslab.knife4j.demo.module.student.entity.User;
import com.ieslab.knife4j.demo.module.student.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

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


@Api(tags = "用户管理")// 配置Controller标题
@ApiSupport(author = "zongshaofeng",order = 1)// 配置作者和顺序，越小越靠前不能小于0
@RestController
@RequestMapping("/student/user")
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "查询全部用户信息")// 配置各个方法的标题
    @ApiOperationSupport(author = "zongshaofeng",order = 1)// 配置作者和顺序，越小越靠前不能小于0，方法上的会覆盖类上的配置
    @GetMapping("/list")
    public ResponseEntity> listUser() {
        List users = userService.list();
        return ResponseEntity.ok(users);
    }

    @ApiOperation(value = "根据用户Id，查询用户信息")
    @ApiOperationSupport(author = "zongshaofeng",order = 2)
    @GetMapping("/{id}")
    public ResponseEntity getUserById(@PathVariable("id") Integer userId) {
        User user = userService.getById(userId);
        return ResponseEntity.ok(user);
    }

    @ApiOperation(value = "保存用户信息")
    @ApiOperationSupport(author = "zongshaofeng",order = 3,ignoreParameters = {"id"})
    @PostMapping("/saveUser")
    public ResponseEntity saveUser(User user) {
        boolean save = userService.save(user);
        return ResponseEntity.ok(save);
    }
}

-Knife4jConfig类：

package com.ieslab.knife4j.demo.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.documentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("演示Knife4j接口文档")
                        .description("@是小宗啊？")
                        .termsOfServiceUrl("http://localhost:8088/api/*")
                        .contact(new Contact("小宗","www.xxx.com","xxx@qq.com"))
                        .version("1.0")
                        .build()
                )
                .groupName("1.0版本")
                .select()
                // 这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.ieslab.knife4j.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

三、总结

其实还有很多的比较复杂的内容都没有涉及到，到目前为止，一般的使用场景应该是足够应付的，如果有新的需求，可进一步去官网进行学习。总之，问题不大。

下周见。

SpringBoot整合Knife4j替代Swagger

Java相关栏目本月热门文章