[Java知识库] 在项目实战中使用Knife4j API 管理

开发: C++知识库 Java知识库 JavaScript Python PHP知识库人工智能区块链大数据移动开发嵌入式开发工具数据结构与算法开发测试游戏开发网络协议系统运维
教程: HTML教程 CSS教程 JavaScript教程 Go语言教程 JQuery教程 VUE教程 VUE3教程 Bootstrap教程 SQL数据库教程 C语言教程 C++教程 Java教程 Python教程 Python3教程 C#教程
数码: 电脑笔记本显卡显示器固态硬盘硬盘耳机手机 iphone vivo oppo 小米华为单反装机图拉丁

-> Java知识库 -> 在项目实战中使用Knife4j API 管理 -> 正文阅读

[Java知识库]在项目实战中使用Knife4j API 管理

文章目录

- 🎆 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();
}