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

界面显示

 

注解使用

  • @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 {
    // ... 省略
}

效果如下:

@Api 注解的常用属性,如下:

  • tags

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

    []

    数组,可以填写多个。

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

    • 如果在多个 Controller 上的 @Apitags 属性,设置一个标签,那么这些 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 注解的废弃属性,不建议使用,有 valuedescriptionbasePathposition

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;
}

效果如下:

@ApiOperation 注解的常用属性,如下:

  • value 属性:API 操作名。

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

@ApiOperation 注解的不常用属性,如下:

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

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

  • httpMethod 属性:请求方法,可选值为 GETHEADPOSTPUTDELETEOPTIONSPATCH 。因为 Swagger 会解析 SpringMVC 的注解,所以一般无需填写。

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

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

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

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

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

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

  • responseContainer 属性:响应结果的容器,可选值为 ListSetMap

  • 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;
}

效果如下:@ApiImplicitParam 示例

@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 {
    // ... 省略
}

效果如下:

@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 方法
}

效果如下:

@ApiModelProperty 注解的常用属性,如下:

  • value 属性:属性的描述。

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

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

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

@ApiModelProperty 注解的不常用属性,如下:

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

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

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

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

  • accessMode 属性:访问模式,有 AccessMode.AUTOAccessMode.READ_ONLYAccessMode.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;
}

 

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值