5.SpringBoot整合Swagger2(Knife4j框架) 及注解配置演示

1. swagger是什么？

总的来说 就是一个接口文档 可支持调试 方便前后端的联调 功能强大 开发必不可少

话不多说 直接开始实战

2. 引入依赖

   <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
     <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.3</version>
        </dependency>

使用最新版的 knife4j依赖 大家也可以直接在maven仓库找到对应的版本

ps:使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

maven仓库跳转

也可以看knife4j的文档进行具体的学习

文档跳转

3. 配置swagger

对应的配置如下 大家可以照这个这个配置改

最关键的是扫描的包名需要与你的一致 否则是不成功的

@Configuration
@EnableSwagger2
public class Knife4jConfiguration {

    @Bean
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("项目的名称")
                        .description("你项目的描述")
                        .contact(new Contact("机智的爆爆哥","http:www.sharpbb.top","1029922944@qq.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("喜欢什么填什么")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("cn.bb"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

4. 效果图

访问 http://localhost:8080/doc.html 就可以看到对应的效果

5.注解配置

如果单单让你见到这个效果 那这篇教程将毫无意义 重点将来总结下常用注解的使用

5.1 @Api

用于类

• 该注解将一个Controller（Class）标注为一个swagger资源（API）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。该注解包含以下几个重要属性：
• tags
  API分组标签。具有相同标签的API将会被归并在一组内展示。
• value
  如果tags没有定义，value将作为Api的tags使用
• description
  API的详细描述，在1.5.X版本之后不再使用，但实际发现在2.0.0版本中仍然可以使用

我们以controller为例

效果如下 实测发现 value description都没有什么效果 在controller上直接使用tag即可

5.2 @ApiOperation

用于方法

• 在指定的（路由）路径上，对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有：
  • value
    对操作的简单说明，长度为120个字母，60个汉字。
  • notes
    对操作的详细说明。
  • httpMethod
    HTTP请求的动作名，可选值有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
  • code
    默认为200，有效值必须符合标准的HTTP Status Code Definitions。

说白了就是用在方法上的
示例如下

效果是这样的 有用的是 value和 notes

5.3 @ApiImplicitParams

用于方法

注解ApiImplicitParam的容器类，以数组方式存储。

这个注解需要结合 @ApiImplicitParam 使用

5.4 @ApiImplicitParam

用于方法

对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定，但这个@ApiImplicitParam注解可以以统一的方式定义参数列表，也是在Servelet及非JAX-RS环境下，唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性：

• name
  参数名称
• value
  参数的简短描述
• required
  是否为必传参数
• dataType
  参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
• paramType
  参数的传入（请求）类型，可选的值有path, query, body, header or form。
  
  重点讲一下 paramType 不同参数的含义

1. header 请求头参数的获取 可用于 @RequestHeader
2. query get请求的参数拼接 可用于 @RequestParam
3. path 用于restful请求参数的获取 可用于 @PathVariable
4. body放在post 请求体 可用于@RequestBody
5. form 表单提交的形式

ps：细心的小伙伴可以看到 如果传的参数为数组，可以使用 allowMultiple = true 标注参数可以为多个

5.5 @ApiParam

用于方法参数

• 增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有：
  • required
    是否为必传参数
  • value
    参数简短说明

示例如下 主要是用在参数上 与@RequestParam有点类似 但它还能显示描述信息

但有一点需要注意 当你没有在方法参数上加任何注解时 请求参数的类型是body 这个有点坑

我们希望的是query 可以加@RequestParam来解决 或者使用上面的一组注解

效果如下 如果单单是参数描述 这个更方便一些

5.6 @ApiResponses

用于方法

注解@ApiResponse的包装类，数组结构。即使需要使用一个@ApiResponse注解，也需要将@ApiResponse注解包含在注解@ApiResponses内。

该注解与上面的 @ApiImplicitParam类似 也是需要配套使用的

5.7 @ApiResponse

用于方法

描述一个操作可能的返回结果。当REST API请求发生时，这个注解可用于描述所有可能的成功与错误码。

可以用，也可以不用这个注解去描述操作的返回类型，但成功操作的返回类型必须在@ApiOperation中定义。

如果API具有不同的返回类型，那么需要分别定义返回值，并将返回类型进行关联。但Swagger不支持同一返回码，多种返回类型的注解。

注意：这个注解必须被包含在@ApiResponses注解中。

• code
  HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
• message
  更加易于理解的文本消息
• response
  返回类型信息，必须使用完全限定类名，比如“com.xyz.cc.Person.class”。
• responseContainer
  如果返回类型为容器类型，可以设置相应的值。有效值为 “List”, “Set” or “Map”，其他任何无效的值都会被忽略。

示例如下

效果如下 发现根本没什么效果。。。 可能是我写的有问题 //todo…

5.8 @ApiModel

用于实体类

提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的model结构说明。主要属性有：

• value
  model的别名，默认为类名
• description
  model的详细描述

对于这个value 我需要重点讲一下 因为被他坑到过了 总的来说 如果类名是相同的

必须指定不同的value值 否则value会以类名为准 造成某些注释的失效

跟下面的注解一起示范

5.9 @ApiModelProperty

用于实体类的属性

对model属性的注解，主要的属性值有：

• value
  属性简短描述
• example
  属性的示例值
• required
  是否为必须值

示例如下

发现@ApiModel 描述信息好像没什么用 没有在哪里显示出来 用value即可

这里可以看到有个对应的示例展示出来了 虽然我觉得可有可无吧。。。

6. 小总结

总结下 在我们平时的开发中 该怎么配合使用呢

1.在controller上 我们使用 @Api 指明一下tag即可

2.在控制层对应的方法上 只需要注明 @ApiOperation 的value即可

3.如果要对方法参数进行说明

就使用 @ApiImplicitParams+ @ApiImplicitParam

指定 name 方法参数 value 方法说明 paramType 请求参数说明

@ApiParam 其实并不好用… 虽然可以少写一些代码

4.当你的方法参数接受的是是你自定义的对象时 那么就要用到 @ApiModel +@ApiModelProperty 了

这两个最好搭配使用 不要加了@ApiModelProperty 忘记了@ApiModel 指定value

因为在类名相同的情况下

会导致某些属性的注释缺失 之前我一直以为是缓存的缘故 其实就是配置出的问题 切记！！！！

教程就先到这里了 可能后续补充 拜！

这个世界上 有一些错觉是危险的，一个是认为对方是特别的 ，一个是认为自己是特别的。