Springboot集成knife4j实现风格化API文档

Springboot集成knife4j实现风格化API文档

POM引入插件

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

配置加载

 package com.pengsn.apiserver.videoconference.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
 
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
 
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.EnableSwagger2;
 
/**
 * 配置
 */
 
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
 
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                // 这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage(
                                    "com.pengsn.apiserver.videoconference.business"))
                .paths(PathSelectors.any()).build();
        return docket;
    }
 
    private ApiInfo apiInfo() {
        Contact contact = new Contact("pengsn", "", "");
        return new ApiInfoBuilder().title("视频会议接口描述").
        description("视频会议接口描述").contact(contact).version("1.0").build();
    }
}

访问地址

访问地址是：http://${host}:${port}/doc.html

界面显示

Springboot集成knife4j实现风格化API文档

 

注解使用

  • @Api(tags="controller description")； 作用于 类

  • @ApiOperator(value="接口名称", notes="接口描述") 作用于 方法

  • @ApiOperationSupport(order=1) 排序

 

2.5 注解

在 swagger-annotations 库中，在 io.swagger.annotations 包路径下，提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的，大多数场景下，只需要使用到我们在 「2.4 UserController」 中用到的注解。

2.5.1 @Api

@Api 注解，添加在 Controller 类上，标记它作为 Swagger 文档资源。

示例如下：

// UserController.java
@RestController
@RequestMapping("/users")
@Api(tags = "用户 API 接口")
public class UserController {
    // ... 省略
}

效果如下：

Springboot集成knife4j实现风格化API文档

@Api 注解的常用属性，如下：

  • tags

    属性：用于控制 API 所属的标签列表。

    []

    数组，可以填写多个。

    • 可以在一个 Controller 上的 @Api 的 tags 属性，设置多个标签，那么这个 Controller 下的 API 接口，就会出现在这两个标签中。

    • 如果在多个 Controller 上的 @Api 的 tags 属性，设置一个标签，那么这些 Controller 下的 API 接口，仅会出现在这一个标签中。

    • 本质上，tags 就是为了分组 API 接口，和 Controller 本质上是一个目的。所以绝大数场景下，我们只会给一个 Controller 一个唯一的标签。例如说，UserController 的 tags 设置为 "用户 API 接口" 。

@Api 注解的不常用属性，如下：

  • produces 属性：请求请求头的可接受类型( Accept )。如果有多个，使用 , 分隔。

  • consumes 属性：请求请求头的提交内容类型( Content-Type )。如果有多个，使用 , 分隔。

  • protocols 属性：协议，可选值为 "http"、"https"、"ws"、"wss" 。如果有多个，使用 , 分隔。

  • authorizations 属性：授权相关的配置，[] 数组，使用 @Authorization 注解。

  • hidden 属性：是否隐藏，不再 API 接口文档中显示。

@Api 注解的废弃属性，不建议使用，有 value、description、basePath、position 。

2.5.2 @ApiOperation

@ApiOperation 注解，添加在 Controller 方法上，标记它是一个 API 操作。

示例如下：

// UserController.java
@GetMapping("/list")
@ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试，所以返回用户全列表")
public List<UserVO> list() {
    // 查询列表
    List<UserVO> result = new ArrayList<>();
    result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
    result.add(new UserVO().setId(2).setUsername("woshiyutou"));
    result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));
    // 返回列表
    return result;
}

效果如下：

Springboot集成knife4j实现风格化API文档

@ApiOperation 注解的常用属性，如下：

  • value 属性：API 操作名。

  • notes 属性：API 操作的描述。

@ApiOperation 注解的不常用属性，如下：

  • tags 属性：和 @API 注解的 tags 属性一致。

  • nickname 属性：API 操作接口的唯一标识，主要用于和第三方工具做对接。

  • httpMethod 属性：请求方法，可选值为 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH 。因为 Swagger 会解析 SpringMVC 的注解，所以一般无需填写。

  • produces 属性：和 @API 注解的 produces 属性一致。

  • consumes 属性：和 @API 注解的 consumes 属性一致。

  • protocols 属性：和 @API 注解的 protocols 属性一致。

  • authorizations 属性：和 @API 注解的 authorizations 属性一致。

  • hidden 属性：和 @API 注解的 hidden 属性一致。

  • response 属性：响应结果类型。因为 Swagger 会解析方法的返回类型，所以一般无需填写。

  • responseContainer 属性：响应结果的容器，可选值为 List、Set、Map 。

  • responseReference 属性：指定对响应类型的引用。这个引用可以是本地，也可以是远程。并且，当设置了它时，会覆盖 response 属性。说人话，就是可以忽略这个属性，哈哈哈。

  • responseHeaders 属性：响应头，[] 数组，使用 @ResponseHeader 注解。

  • code 属性：响应状态码，默认为 200 。

  • extensions 属性：拓展属性，[] 属性，使用 @Extension 注解。

  • ignoreJsonView 属性：在解析操作和类型，忽略 JsonView 注释。主要是为了向后兼容。

@ApiOperation 注解的废弃属性，不建议使用，有 position 。

2.5.3 @ApiImplicitParam

@ApiImplicitParam 注解，添加在 Controller 方法上，声明每个请求参数的信息。

示例如下：

// UserController.java
​
@PostMapping("/delete")
@ApiOperation(value = "删除指定用户编号的用户")
@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")
public Boolean delete(@RequestParam("id") Integer id) {
    // 删除用户记录
    Boolean success = false;
    // 返回是否更新成功
    return success;
}

效果如下：Springboot集成knife4j实现风格化API文档

@ApiImplicitParam 注解的常用属性，如下：

  • name 属性：参数名。

  • value 属性：参数的简要说明。

  • required 属性：是否为必传参数。默认为 false 。

  • dataType 属性：数据类型，通过字符串 String 定义。

  • dataTypeClass 属性：数据类型，通过 dataTypeClass 定义。在设置了 dataTypeClass 属性的情况下，会覆盖 dataType 属性。推荐采用这个方式。

  • paramType

    属性：参数所在位置的类型。有如下 5 种方式：

    • "path" 值：对应 SpringMVC 的 @PathVariable 注解。

    • 【默认值】"query" 值：对应 SpringMVC 的 @PathVariable 注解。

    • "body" 值：对应 SpringMVC 的 @RequestBody 注解。

    • "header" 值：对应 SpringMVC 的 @RequestHeader 注解。

    • "form" 值：Form 表单提交，对应 SpringMVC 的 @PathVariable 注解。

    • ???? 绝大多数情况下，使用 "query" 值这个类型即可。

  • example 属性：参数值的简单示例。

  • examples 属性：参数值的复杂示例，使用 @Example 注解。

@ApiImplicitParam 注解的不常用属性，如下：

  • defaultValue 属性：默认值。

  • allowableValues

    属性：允许的值。如果要设置多个值，有两种方式：

    • 数组方式，即 {value1, value2, value3} 。例如说，{1, 2, 3} 。

    • 范围方式，即 [value1, value2] 或 [value1, value2) 。例如说 [1, 5] 表示 1 到 5 的所有数字。如果有无穷的，可以使用 (-infinity, value2] 或 [value1, infinity) 。

  • allowEmptyValue 属性：是否允许空值。

  • allowMultiple 属性：是否允许通过多次传递该参数来接受多个值。默认为 false 。

  • type 属性：搞不懂具体用途，对应英文注释为 Adds the ability to override the detected type 。

  • readOnly 属性：是否只读。

  • format 属性：自定义的格式化。

  • collectionFormat 属性：针对 Collection 集合的，自定义的格式化。

当我们需要添加在方法上添加多个 @ApiImplicitParam 注解时，可以使用 @ApiImplicitParams 注解中添加多个。示例如下：

@ApiImplicitParams({ // 参数数组
        @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024"), // 参数一
        @ApiImplicitParam(name = "name", value = "昵称", paramType = "query", dataTypeClass = String.class, required = true, example = "芋道"), // 参数二
})

2.5.4 @ApiModel

@ApiModel 注解，添加在 POJO 类，声明 POJO 类的信息。而在 Swagger 中，把这种 POJO 类称为 Model 类。所以，我们下文就统一这么称呼。

示例如下：

// UserVO.java

@ApiModel("用户 VO")
public class UserVO {
    // ... 省略
}

效果如下：

Springboot集成knife4j实现风格化API文档

@ApiModel 注解的常用属性，如下：

  • value 属性：Model 名字。

  • description 属性：Model 描述。

@ApiModel 注解的不常用属性，如下：

  • parent 属性：指定该 Model 的父 Class 类，用于继承父 Class 的 Swagger 信息。

  • subTypes 属性：定义该 Model 类的子类 Class 们。

  • discriminator 属性：搞不懂具体用途，对应英文注释为 Supports model inheritance and polymorphism.

  • reference 属性：搞不懂具体用途，对应英文注释为 Specifies a reference to the corresponding type definition, overrides any other metadata specified

2.5.5 @ApiModelProperty

@ApiModelProperty 注解，添加在 Model 类的成员变量上，声明每个成员变量的信息。

示例如下：

// UserVO.java

@ApiModel("用户 VO")
public class UserVO {
    @ApiModelProperty(value = "用户编号", required = true, example = "1024")
    private Integer id;
    @ApiModelProperty(value = "账号", required = true, example = "yudaoyuanma")
    private String username;
    // ... 省略 set/get 方法
}

效果如下：

Springboot集成knife4j实现风格化API文档

@ApiModelProperty 注解的常用属性，如下：

  • value 属性：属性的描述。

  • dataType 属性：和 @ApiImplicitParam 注解的 dataType 属性一致。不过因为 @ApiModelProperty 是添加在成员变量上，可以自动获得成员变量的类型。

  • required 属性：和 @ApiImplicitParam 注解的 required 属性一致。

  • example 属性：@ApiImplicitParam 注解的 example 属性一致。

@ApiModelProperty 注解的不常用属性，如下：

  • name 属性：覆盖成员变量的名字，使用该属性进行自定义。

  • allowableValues 属性：和 @ApiImplicitParam 注解的 allowableValues 属性一致。

  • position 属性：成员变量排序位置，默认为 0 。

  • hidden 属性：@ApiImplicitParam 注解的 hidden 属性一致。

  • accessMode 属性：访问模式，有 AccessMode.AUTO、AccessMode.READ_ONLY、AccessMode.READ_WRITE 三种，默认为 AccessMode.AUTO 。

  • reference 属性：和 @ApiModel 注解的 reference 属性一致。

  • allowEmptyValue 属性：和 @ApiImplicitParam 注解的 allowEmptyValue 属性一致。

  • extensions 属性：和 @ApiImplicitParam 注解的 extensions 属性一致。

@ApiModelProperty 注解的废弃属性，不建议使用，有 readOnly 。

2.5.6 @ApiResponse

在大多数情况下，我们并不需要使用 @ApiResponse 注解，因为我们会类似 UserController#get(id) 方法这个接口，返回一个 Model 即可。所以 @ApiResponse 注解，艿艿就简单讲解，嘿嘿。

@ApiResponse 注解，添加在 Controller 类的方法上，声明每个响应参数的信息。

@ApiResponse 注解的属性，基本已经被 @ApiOperation 注解所覆盖，如下：

  • message 属性：响应的提示内容。

  • code 属性：和 @ApiOperation 注解的 code 属性一致。

  • response 属性：和 @ApiOperation 注解的 response 属性一致。

  • reference 属性：和 @ApiOperation 注解的 responseReference 属性一致。

  • responseHeaders 属性：和 @ApiOperation 注解的 responseHeaders 属性一致。

  • responseContainer 属性：和 @ApiOperation 注解的 responseContainer 属性一致。

  • examples 属性：和 @ApiOperation 注解的 examples 属性一致。

当我们需要添加在方法上添加多个 @ApiResponse 注解时，可以使用 @ApiResponses 注解中添加多个。

2.5.7 @DynamicParameters 动态字段注释

@PostMapping("/createOrder421")
@ApiOperation(value = "fastjson-JSONObject-动态创建显示参数")
@ApiOperationSupport(params = @DynamicParameters(name = "CreateOrderModel",properties = {
        @DynamicParameter(name = "id",value = "注解id",example = "X000111",required = true,dataTypeClass = Integer.class),
        @DynamicParameter(name = "name",value = "订单编号",required = false)
}))
public Rest<JSONObject> createOrder12222(@RequestBody JSONObject jsonObject){
    Rest<JSONObject> r=new Rest<>();
    r.setData(jsonObject);
    return r;
}

@PostMapping("/createOrder422")
@ApiOperation(value = "jdk-Map-动态创建显示参数")
@DynamicParameters(name = "CreateOrderMapModel",properties = {
            @DynamicParameter(name = "id",value = "注解id",example = "X000111",required = true,dataTypeClass = Integer.class),
            @DynamicParameter(name = "name",value = "订单编号"),
            @DynamicParameter(name = "name1",value = "订单编号1"),
            @DynamicParameter(name = "orderInfo",value = "订单信息",dataTypeClass = Order.class),
    })
public Rest<Map> createOrder12232(@RequestBody Map map){
    Rest<Map> r=new Rest<>();
    r.setData(map);
    return r;
}

 

2.5.8 @DynamicResponseParameters 动态添加响应类注释字段

@ApiOperationSupport(
    responses = @DynamicResponseParameters(properties = {
        @DynamicParameter(value = "编号",name = "id"),
        @DynamicParameter(value = "名称",name = "name"),
        @DynamicParameter(value = "订单",name = "orderDate",dataTypeClass = OrderDate.class)
    })
)
@ApiOperation(value = "响应JSONObject类型")
@GetMapping("/jsonObject")
public JSONObject jsonObjectxxxx(){
    JSONObject jsonObject=new JSONObject();
    jsonObject.put("name","xx");
    return jsonObject;
}

 

相关文章：

  • 2021-07-02
  • 2022-12-23
  • 2022-12-23
  • 2022-12-23
  • 2022-12-23
  • 2021-06-27
  • 2022-12-23
  • 2021-04-08
猜你喜欢
  • 2021-09-08
  • 2022-12-23
  • 2021-10-20
  • 2021-12-10
  • 2021-05-23
  • 2022-01-15
相关资源
相似解决方案
热门标签
Java Python linux javascript Mysql C# Docker 算法 前端 SpringBoot Redis Vue spring 设计模式 .net core .net kubernetes c++ 数据库 数据结构 大数据 js 机器学习 微服务 Android Go 程序员 面试 JVM ASP.net core 云原生 人工智能 后端 PHP git CSS golang k8s Nginx Django mybatis 深度学习 多线程 React 架构 devops 爬虫 云计算 Spring Boot LeetCode