【Swagger2】

五、Swagger配置

可以在项目中创建SwaggerConfig，进行配置文档内容。

1、配置基本信息

Docket：摘要对象，通过对象配置描述文件的信息。

apiInfo：设置描述文件中info。参数类型ApiInfo

select()：返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象

ApiInfoBuilder：ApiInfo构建器。

显示效果如下：

2、设置扫描的包

可以通过apis()方法设置哪个包中内容被扫描

3、自定义注解设置不需要生成接口文档的方法

3.1 自定义注解

注解名称随意。

3.2 添加规则

通过public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。

public static <T> Predicate<T> not(Predicate<T> predicate) :表示不允许的条件。

withMethodAnnotation：表示此注解是方法级别注解。

3.3 添加NotIncludeSwagger注解

在不需要生成接口文档的方法上面添加@NotIncludeSwagger注解后，该方法将不会被Swagger进行生成在接口文档中。

4、设置范围

通过public ApiSelectorBuilder paths(Predicate<String> selector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。

如何希望全部扫描可以使用paths(PathSelectors.any())

六、Swagger2常用注解

1、Api

@Api是类上注解。控制整个类生成接口信息的内容。

tags：类的名称。可以有多个值，多个值表示多个副本。

description：描述，已过时。

在swagger-ui.html中显示效果。

2、ApiOperation

@ApiOperation写在方法上，对方法进行总体描述

● value：接口描述

● notes：提示信息

代码示例：

在swagger-ui中显示效果

3、ApiParam

@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。

name：参数名称

value：参数描述

required：是否是必须

swagger-ui显示效果如下：

4、ApiModel

@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。

● value：名称

● description：描述

代码示例：

swagger-ui.html效果展示

5、ApiModelProperty

@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。

● value：描述

● name：重写属性名

● required：是否是必须的

● example：示例内容

● hidden：是否隐藏。

代码示例：

swagger-ui.html效果展示

6、ApiIgnore

@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解。

7、ApiImplicitParam

@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。

● name：属性名

● value：描述

● required：是否是必须的

● paramType：属性类型

● dataType：数据类型

代码示例：

swagger-ui.html效果展示

如果希望在方法上配置多个参数时，使用@ApiImplicitParams进行配置。示例如下：

海量Java学习资料，大厂面试题，项目练习题，统统免费提供，只要关注，那就会有收获~笔芯~