Knife4j组件应用

1. 概述

knife4j是国人开发的一个为JavaMVC框架生成Api文档的解决方案,取名knif4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

2. 设计目标

  • 开发人员更加方便的基于API文档进行测试

  • 生成离线API文档，为前后端的开发人员的沟通提供便利手段。

3. Knife4j快速上手

  • 第1步: 添加项目依赖

    注意: 该依赖只能手动添加，不能在创建SpringBoot工程时勾选；

    <!--添加Knife4j依赖-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

  • 第2步: 在application.properties配置文件中添加如下配置

    knife4j.enable=true

  • 第3步: 创建配置类

    工程目录下创建base.config.Knife4jConfig

    package cn.tedu._02notice.base.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.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    //配置Swagger2的Docket的Bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(apiInfo())
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                // apis()：指定要生成哪个包下的 API 文档
                .apis(RequestHandlerSelectors.basePackage("cn.tedu._02notice.controller"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }

    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("通知管理项目")
                // 文档描述信息
                .description("通知管理项目在线API文档")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

  • 第4步:启动项目测试
    启动项目，通过 http://localhost:8080/doc.html 即可访问在线API文档。

4. 常用注解应用分析

在API文档中，菜单中的各名称默认是根据控制器类名、方法名转换得到的，通常会通过注解对类、方法、参数机型配置描述，常用注解说明如下

4.1. @Api注解

是添加在控制器类上的注解，通过此注解的tags属性可以修改原本显示控制器类名称的位置的文本，通常，建议在配置的tags值上添加序号，例如：“1. 管理员模块”、“2. 商品模块”，则框架会根据值进行排序。

  • 参数说明

    tags：配置模块名称

  • 代码示例

    // 1\. NoticeController
@Api(tags = "01.通知管理模块")
public class UserController {...}

// 2\. UserController
@Api(tags = "02.用户管理模块")
public class WeiboController {...}

4.2. @ApiOperation注解

是添加在控制器类中处理请求的方法上的注解，用于配置此方法处理的请求在API文档中显示的文本。

  • 参数说明
    value：配置业务名称
  • 代码示例 
    @ResponseBody
@PostMapping("/v1/notice/add")
@ApiOperation("新增公告功能")
public JsonResult addNotice(NoticeAddParam noticeAddParam){}

4.3. @ApiOperationSupport注解

是添加在控制器类中处理请求的方法上的注解，通过配置其order属性可以指定各方法在API文档中的显示顺序。

@ResponseBody
@PostMapping("/v1/notice/add")
@ApiOperationSupport(order = 10)
@ApiOperation("新增公告功能")
public JsonResult addNotice(NoticeAddParam noticeAddParam){}

4.4. @ApiModelProperty注解

是添加在POJO类的属性上的注解，用于对请求参数或响应结果中的某个属性进行说明，主要通过其value属性配置描述文本，并可通过example属性配置示例值

  • 参数说明

    • value属性：配置参数名称
    • required属性：配置是否必须提交此请求参数
    • example属性：配置示例值

    注意：如果配置了 required=true,只是一种显示效果，Knife4j框架并不具备检查功能

  • 代码示例

    @Data
public class NoticeAddParam {
    @ApiModelProperty(value = "公告标题", required = true, example = "紧急通知...")
    private String title;
    @ApiModelProperty(value = "公告类型", required = true)
    private Integer type;
    @ApiModelProperty(value = "公告内容", required = true)
    private String content;
    @ApiModelProperty(value = "公告状态", required = true)
    private Integer status;
}

4.5. @ApiImplicitParam注解

是添加在控制器类中处理请求的方法上的注解，也可以作为@ApiImplicitParams注解的参数值，主要用于配置非封装的参数，主要配置name、value、example、required、dataType属性

  • 参数说明

    • name：指定参数名称（参数变量名）
    • value：配置参数名称
    • dataType：配置数据类型
    • required：配置是否必须提交此请求参数
    • example：配置参数的示例值

    注意：一旦使用此注解，各个参数的数据类型默认都会显示String，可以通过dataType指定数据类型

  • 代码示例

    @ResponseBody
@GetMapping("/v1/notice/detail")
@ApiOperationSupport(order = 30)
@ApiOperation("公告详情功能")
@ApiImplicitParam(name = "id", value = "公告编号", required = true, example = "2", dataType = "long")
public JsonResult noticeDetail(Long id){

4.6. @ApiImplicitParams注解

是添加在控制器类中处理请求的方法上的注解，当方法有多个非封装的参数时，在方法上添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数。

代码示例

    @ApiOperationSupport(order = 30)
    @ApiOperation("查询会员信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "city", value = "城市名", example = "1",
                required = true, dataType = "string"),
            @ApiImplicitParam(name = "gender", value = "性别", example = "1",
                dataType = "string")
    })
    @GetMapping("/listByExample")
    public Object doListByExample(String city, String gender) {
        throw new RuntimeException("此功能尚未实现");
    }

4.7. @ApiIgnore注解

添加在处理请求的方法的参数上，用于表示API文档框架应该忽略此参数。
代码示例

@ResponseBody
@PostMapping("/v1/notice/del")
@ApiOperationSupport(order = 40)
@ApiOperation("删除公告功能")
public JsonResult deleteNotice(@RequestBody @ApiIgnore Long id){}

5. 限定请求方式

API文档中默认每个功能会展示7种请求方式，遵循RESTful规则将 @RequestMapping 注解修改为对应请求方法的注解，比如：@GetMapping @PostMapping @PutMapping @DeleteMapping 注解，重启工程后刷新测试。

6. 导出离线API文档

  • 第1步: 文档管理 - 离线文档 中存在多种格式的导出格式


  • 第2步: 选择合适的文档格式，导出即可到本地磁盘

©著作权归作者所有,转载或内容合作请联系作者
平台声明：文章内容（如有图片或视频亦包括在内）由作者上传并发布，文章内容仅代表作者本人观点，简书系信息发布平台，仅提供信息存储服务。

推荐阅读更多精彩内容