在项目实战中使用Knife4j API 管理

🎆 Knife4j API 管理

1、前言

​ 最近开发了一个Neo4j+elasticsearch+mysql作为数据库的后台管理系统，主要作用是利用图数据库的特性来存储不同学科中的知识点数据，该系统目前初版已开发完成，抱着将项目做得更好的想法，想要生成一套接口文档试试，以通过swagger了解到了Knife4j

2、Knife4j

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目

一开始项目初衷是为了写一个增强版本的swagger的前端ui,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。

因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

主要的变化是,项目的相关类包路径更换为com.github.xiaoymin.knife4j前缀,开发者使用增强注解时需要替换包路径

后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)

3、使用说明

​ 在项目中添加对应自己springboot版本的knife4j版本：

​ 本人的springboot版本为2.1.4所以选择knife4j版本为2.0.2，添加依赖：

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

​ 如果开发者使用OpenAPI3的结构，底层框架依赖springfox3.0.0,可以考虑Knife4j的3.x版本

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.3</version>
</dependency>

​ 想要使用更多功能需要使用springboot2.2x版本以上！！！！！！

​ 官方文档： https://doc.xiaominfo.com/knife4j/documentation/help.html

在所需要的微服务中添加如下config类：

代码：

package com.yxinmiracle.question.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.HashSet;

/**
 * @version 1.0
 * @author： YxinMiracle
 * @date： 2021-10-16 15:46
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        HashSet<String> strings = new HashSet<>();
        //设置返回的值是JSON格式
        strings.add("application/json");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .produces(strings)
                .groupName("question-group")//商品组
                .select()
                //扫描扫描包路径 controller所在的
                .apis(RequestHandlerSelectors.basePackage("com.yxinmiracle"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置标题
                .title("使图行者（PEC2.0）后台管理系统RestFul APIs接口文档")

                .description("使图行者（PEC2.0）后台管理系统在线API接口文档")
                //访问地址
                .termsOfServiceUrl("https:/www.yxinmiracle.com/")
                //联系人
                .contact("yxinmiracle@gmail.com")
                //版本
                .version("2.0")
                //构建
                .build();
    }
}

3.1、api注解

@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源，使用方式代码如下所示。

其中就会在文档中显示：

​ 点开上图中的card-item，里面就是该controller中所有的接口，参考代码如下：

package com.yxinmiracle.question.controller;

import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.yxinmiracle.core.AbstractCoreController;
import com.yxinmiracle.question.pojo.Course;
import com.yxinmiracle.question.service.CourseService;
import entity.PageResult;
import entity.Result;
import entity.StatusCode;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/****
 * @Author:YxinMiracle
 * @Description:
 *****/

@RestController
@RequestMapping("/course")
@Api(value = "课程数据管理", tags = "课程数据管理-写文档注释我是认真的")
public class CourseController extends AbstractCoreController<Course> {

    private CourseService courseService;

    @Autowired
    public CourseController(CourseService courseService) {
        super(courseService, Course.class);
        this.courseService = courseService;
    }

    @ApiOperationSupport(author = "yxinmiracle@gmail.com")
    @ApiOperation("得到课程的全部数据")
    @PostMapping("/all")
    public Result getCourseAllData(@ApiParam(value = "请求全部课程数据的page参数") @RequestBody PageResult pageResult) {
        PageResult retPageResult = courseService.getCourseAllData(pageResult);
        return new Result(true, StatusCode.OK, "查询课程数据", retPageResult);
    }

    @ApiOperation("添加课程数据")
    @PostMapping("/addCourse")
    public Result addCourse(@ApiParam(value = "添加课程所携带的Course数据") @RequestBody Course course) {
        courseService.addCourse(course);
        return new Result(true, StatusCode.OK, "添加课程数据成功");
    }

    @ApiOperation("更新课程数据")
    @PostMapping("/updateCourse")
    public Result updateCourse(@ApiParam(value = "更新课程所携带的Course数据") @RequestBody Course course) {
        courseService.updateCourse(course);
        return new Result(true, StatusCode.OK, "更新课程数据成功");
    }
}

3.2、ApiModel

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示。

显示效果：

3.3、ApiModelProperty

@ApiModelProperty() 用于字段，表示对 model 属性的说明。使用方式代码如下所示。

package com.yxinmiracle.question.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.persistence.*;
import java.io.Serializable;
import java.util.Date;

/****
 * @Author:YxinMiracle
 * @Description:Course构建
 *****/
@AllArgsConstructor
@NoArgsConstructor
@Data
@Table(name = "course")
@ApiModel(description = "课程数据", value = "Course")
public class Course implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "c_id")
    @ApiModelProperty(value = "课程Id", required = false)
    private Integer cId;//

    @ApiModelProperty(value = "课程名称", required = true)
    @Column(name = "name")
    private String name;//课程名称

    @ApiModelProperty(value = "图片链接", required = false)
    @Column(name = "image_url")
    private String imageUrl;//课程图片展示

    @ApiModelProperty(value = "创建时间", required = true)
    @Column(name = "create_date")
    private Date createDate;//创建的时间

    @ApiModelProperty(value = "是否展示", required = true)
    @Column(name = "is_show")
    private Integer isShow;//0为不展示 1为展示
}

3.4、ApiParam

@ApiParam 用于 Controller 中方法的参数说明。使用方式代码如下所示。

• value：参数说明
• required：是否必填

3.5 、ApiImplicitParam 和 ApiImplicitParams

用于方法上，为单独的请求参数进行说明。使用方式代码如下所示。

exp: “/user?id=xxxx”

@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "query", required = true, defaultValue = "1") })
@GetMapping("/user")
public UserDto getUser(@RequestParam("id") String id) {
    return new UserDto();
}

• name：参数名，对应方法中单独的参数名称。
• value：参数中文说明。
• required：是否必填。
• paramType：参数类型，取值为 path、query、body、header、form。
• dataType：参数数据类型。
• defaultValue：默认值。

4、整体效果

主页：

其中一个接口：

导出离线api文档：

截图: