Knife4j系列--使用-教程-实例-配置 详细讲解

Knife4j系列--使用-教程-实例-配置 详细讲解

Knife4j

Knife4j是基于springboot构建的一个文档生成工具,它可以让开发者为我们的应用生成API文档,目的是可以更加方便的基于API文档进行测试,生成的文档还可以导出,然后给到前端开发团队,前端开发团队可以基于API接口写具体的调用。

1 Knife4j的优点

  • Knife4j 功能强大,易于操作。
  • Knife4j 的UI界面非常美观,使用非常流畅。
  • Knife4j 可以高度定制化,让其符合你的项目需求,提升用户体验。
  • Knife4j 的支持性比较好,可以满足大部分的开发需求。

2 Knife4j快速上手(掌握基本应用即可)

2.1 pom.xml添加依赖

在你的SpringBoot项目的pom.xml文件中,添加如下依赖:

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

2.2 配置Swagger的相关信息

工程目录下创建config.Knife4jConfig

java">package ***.tedu.weibo.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 {//对于配置类要求可以看懂即可,不用反复去写,将来可以CV
    //配置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("***.tedu.weibo.controller"))
                // paths():指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any(),表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }
    private static final String API_TILE="微博项目";
    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title(API_TILE)
                // 文档描述信息
                .description("微博项目在线API文档")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

2.3 查看生成的接口文档

在 SpringBoot 项目启动后,访问 http://localhost:8080/doc.html 地址即可查看生成的Knife4j接口文档。

3 常用注解应用分析

  • @Api注解

    添加在控制器类上的注解,通过此注解的tags属性可以修改原本显示控制器类名称的位置的文本,通常,建议在配置的tags属性值上添加序号,例如:“01. 用户模块”、“02. 微博模块”,则框架会根据值进行排序。

    • 参数说明

      • tags:配置模块名称
    • 代码示例

      // 1. UserController
      @Api(tags = "01.用户管理模块")
      public class UserController {...}
      
      // 2. WeiboController
      @Api(tags = "02.微博管理模块")
      public class WeiboController {...}
      
      // 3. ***mentController
      @Api(tags = "03.评论管理模块")
      public class ***mentController {...}
      
    • 文档效果(重启工程并刷新页面:http://localhost:8080/doc.html#/home

  • @ApiOperation注解

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

    • 参数说明

      • value:配置业务名称
    • 代码示例

      此处以注册功能为例,其他所有方法请添加说明

      /**注册功能*/
      @RequestMapping("reg")
      @ApiOperation(value = "注册功能")
      public int reg(@RequestBody UserRegDTO userRegDTO){...}
      
    • 文档效果(重启工程并刷新页面:http://localhost:8080/doc.html#/home

  • @ApiModelProperty注解

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

    • 参数说明

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

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

    • 代码示例

      以注册功能UserRegDTO为例

      @Data
      public class UserRegDTO {
          @ApiModelProperty(value = "用户名", required = true, example = "赵丽颖")
          private String username;
          @ApiModelProperty(value = "密码", required = true)
          private String password;
          @ApiModelProperty(value = "昵称", required = true)
          private String nickname;
      }
      
    • 文档效果(重启工程并刷新页面:http://localhost:8080/doc.html#/home

  • @ApiImplicitParam注解

    添加在控制器类中处理请求的方法上的注解,主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数

    • 参数说明

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

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

    • 代码示例

      此处以微博详情功能为例

      @ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int")
      public WeiboDetailVO selectById(int id){...}
      
    • 文档效果(重启工程并刷新页面:http://localhost:8080/doc.html#/home

  • @ApiImplicitParams注解

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

    • 代码示例

      此处以微博详情功能为例

      /**微博详情页功能*/
      @GetMapping("selectById")
      @ApiOperation(value = "微博详情功能")
      @ApiImplicitParams(value = {
          @ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int"),
          @ApiImplicitParam(name = "username", value = "用户名", required=true)
      })
      // 额外增加username参数,仅仅用于测试
      public WeiboDetailVO selectById(int id, String username){
          return weiboMapper.selectById(id);
      }
      
    • 文档效果(重启工程并刷新页面:http://localhost:8080/doc.html#/home

  • @ApiIgnore注解

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

    此处以发布微博功能的HttpSession参数为例

    • 代码示例

      // 参数中添加@ApiIgnore注解
      public int insert(@RequestBody WeiboDTO weiboDTO, @ApiIgnore HttpSession session){...}
      
    • 文档效果(重启工程并刷新页面:http://localhost:8080/doc.html#/home

4 限制请求方式

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

5 导出离线API文档

  1. 文档管理 - 离线文档 中存在多种格式的导出格式
  1. 选择合适的文档格式,导出即可到本地磁盘

6 洞悉Knife4j生成API文档原理 (了解)

  1. 自定义注解(模拟Knife4j中注解的定义)
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 @interface ApiProperty{//interface,默认继承Annotation接口
  String value();
  boolean required();
  String example() default "";
 }
 

2.通过注解描述类上属性

class PointDto{
    @ApiProperty(value = "x轴坐标",required = true,example = "10")
    private int x;
    @ApiProperty(value = "y轴坐标",required = true,example = "10")
    private int y;
}

3.通过反射获取注解内容

public class AnnotationTests {
    @Test
    public void doTest() throws NoSuchFieldException {
        //获取PointDto类型的字节码对象(反射起点就是字节码对象)
        Class c1=PointDto.class;
        //获取PointDao类型中的x属性(通过反射获取)
        Field x=c1.getDeclaredField("x");
        //获取x属性上的ApiProperty注解(通过反射获取)
        ApiProperty annotation = x.getAnnotation(ApiProperty.class);
        //获取注解中value等属性的值
        String value = annotation.value();
        String example = annotation.example();
        System.out.println(value+"/"+example);
    }
}

4.通过html/css/js构建页面(doc.html)

转载请说明出处内容投诉
CSS教程_站长资源网 » Knife4j系列--使用-教程-实例-配置 详细讲解

发表评论

欢迎 访客 发表评论

一个令你着迷的主题!

查看演示 官网购买