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

蔚落 2022-09-04 03:52 203阅读 0赞

### 文章目录 ###

*  1. swagger是什么？
 *  2. 引入依赖
 *  3. 配置swagger
 *  4. 效果图
 *  5.注解配置
 *   *  5.1 @Api
     *  5.2 @ApiOperation
     *  5.3 @ApiImplicitParams
     *  5.4 @ApiImplicitParam
     *  5.5 @ApiParam
     *  5.6 @ApiResponses
     *  5.7 @ApiResponse
     *  5.8 @ApiModel
     *  5.9 @ApiModelProperty
 *  6. 小总结

# 1. swagger是什么？ #

![在这里插入图片描述][dd2379bcf98a47c0a9117c88e835afcf.png]  
总的来说 就是一个接口文档 可支持调试 方便前后端的联调 功能强大 开发必不可少

话不多说 直接开始实战

# 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仓库跳转][maven]

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

[文档跳转][Link 1]

# 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][http_localhost_8080_doc.html] 就可以看到对应的效果  
![在这里插入图片描述][eed4dca935774532b71190adb39010ef.png]  
![在这里插入图片描述][1b38a58e41a8435e926764ca42d72be8.png]

# 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为例  
![在这里插入图片描述][572553217646440288ae2229cbeef8db.png]  
效果如下 实测发现 value description都没有什么效果 在controller上直接使用`tag`即可  
![在这里插入图片描述][b0ed03c932de4d3c9e0d00bb0a61a194.png]

## 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。

说白了就是用在方法上的  
示例如下  
![在这里插入图片描述][b593d60225a94d28a4fa306ea1fbee6d.png]  
效果是这样的 有用的是 `value`和 `notes`  
![在这里插入图片描述][9088c8a4e98448288c5657c7cab57e8a.png]

## 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。  
    ![在这里插入图片描述][ae8631d5b3dd4ec78dcc95f395445c2b.png]  
    重点讲一下 `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来解决 或者使用上面的一组注解  
![在这里插入图片描述][33763557a1944222a057ffb0ffe23dba.png]  
效果如下 如果单单是参数描述 这个更方便一些  
![在这里插入图片描述][42eba1eddd714cb5ac361b499f2dbdb2.png]

## 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”，其他任何无效的值都会被忽略。

示例如下  
![在这里插入图片描述][beea533fa559412aadebbc9f473fe799.png]  
效果如下 发现根本没什么效果。。。 可能是我写的有问题 //todo…  
![在这里插入图片描述][f2b8850705574fb78e1b5aa0f0bb61a5.png]

## 5.8 @ApiModel ##

`用于实体类`

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

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

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

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

跟下面的注解一起示范

## 5.9 @ApiModelProperty ##

`用于实体类的属性`

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

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

示例如下  
![在这里插入图片描述][929c76b69fc24f91a974d4da017e7861.png]

发现@ApiModel 描述信息好像没什么用 没有在哪里显示出来 用`value`即可  
![在这里插入图片描述][e6c81e697ad64688873a371f400206e1.png]  
这里可以看到有个对应的示例展示出来了 虽然我觉得可有可无吧。。。  
![在这里插入图片描述][6efda58077114b3ba777fc443cbf7267.png]

# 6. 小总结 #

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

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

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

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

就使用 `@ApiImplicitParams`\+ `@ApiImplicitParam`

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

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

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

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

因为在类名相同的情况下

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

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

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

[dd2379bcf98a47c0a9117c88e835afcf.png]: /images/20220829/f0949ab1afcd4cbaa3e651c143dccdaa.png
[maven]: https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j
[Link 1]: https://doc.xiaominfo.com/knife4j/
[http_localhost_8080_doc.html]: http://localhost:8080/doc.html
[eed4dca935774532b71190adb39010ef.png]: /images/20220829/02c49be075b94e3997d4f44fe7120961.png
[1b38a58e41a8435e926764ca42d72be8.png]: /images/20220829/19dd881e745247138b2615df3a097844.png
[572553217646440288ae2229cbeef8db.png]: /images/20220829/2b1286d17d6d49c49e1d00d7981ccb1d.png
[b0ed03c932de4d3c9e0d00bb0a61a194.png]: /images/20220829/c7c054a1d011403981f70fbc5fbeeafa.png
[b593d60225a94d28a4fa306ea1fbee6d.png]: /images/20220829/8774a12938ff4899981f4bee5e021aab.png
[9088c8a4e98448288c5657c7cab57e8a.png]: /images/20220829/42f39e63b8674b868a6adce8bbc5ece1.png
[ae8631d5b3dd4ec78dcc95f395445c2b.png]: /images/20220829/44db1c9a91734769ad11a93c8ad84576.png
[33763557a1944222a057ffb0ffe23dba.png]: /images/20220829/bcade00cc0654cd6a4f1ea936c411f8c.png
[42eba1eddd714cb5ac361b499f2dbdb2.png]: /images/20220829/3d05ac67f45c42f1a237730720b631a2.png
[beea533fa559412aadebbc9f473fe799.png]: /images/20220829/b3a4d28a79d94be9982d0ef0b235a884.png
[f2b8850705574fb78e1b5aa0f0bb61a5.png]: /images/20220829/8b34b88af4ec42b5a1111ba2ed13b5d3.png
[929c76b69fc24f91a974d4da017e7861.png]: /images/20220829/343bf5c0b66f461cbac37a89ea129005.png
[e6c81e697ad64688873a371f400206e1.png]: /images/20220829/4a449c7916794e20a73067b8f1318211.png
[6efda58077114b3ba777fc443cbf7267.png]: /images/20220829/2a05811f1c9a47ce95ca435b3c6b99f2.png?