Swagger信息配置与常用注解

标签：常用 name required value 注解 Swagger Docket public

转载自：https://blog.csdn.net/donglinjob/article/details/108550887

 Swagger信息配置与常用注解

一、 Swagger  配置

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

1 配置基本信息

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

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

select():返回 ApiSelectorBuilder 对象，通过对象调用 build()可以

创建 Docket 对象

ApiInfoBuilder：ApiInfo 构建器。

1.   @Configuration
2.   public class SwaggerConfig {
3.   @Bean
4.   public Docket getDocket(){
5.   return w new Docket(DocumentationType. SWAGGER_2 )
6.   .apiInfo(swaggerDemoApiInfo())
7.   .select()
8.   .build();
9.   }
10.   private ApiInfo swaggerDemoApiInfo(){
11.   return new ApiInfoBuilder().contact(w new Contact("北京尚学堂",  "http://www.bjsxt.com","[email protected]"))
12.   //文档标题
13.   .title("这里是Swagger的标题")
14.   //文档描述
15.   .description("这里是Swagger的描述")
16.   //文档版本
17.   .version( "1.0.0")
18.   .build();
19.   }
20.   }

显示效果如下：

2 设置扫描的包

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

1.   @Bean
2.   public Docket getDocket() {
3.   return new Docket(DocumentationType. SWAGGER_2 )
4.   .apiInfo(getApiInfo())
5.   .select()
6.   .apis(RequestHandlerSelectors. basePackage ( "com.bjsxt.controller"))
7.   .build();
8.   }

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

3.1 自定义注解

注解名称随意。

1.   @Target({ElementType.METHOD })
2.   @Retention(RetentionPolicy.RUNTIME )
3.   public @interface NotIncludeSwagger {
4.   }

3.2 添加规则

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

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

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

1.   @Bean
2.   public Docket getDocket(){
3.   return w new Docket(DocumentationType.SWAGGER_2 )
4.   .apiInfo(swaggerDemoApiInfo())
5.   .select()
6.   .paths(allowPaths())
7.   .apis( not ( ( withMethodAnnotation (NotIncludeSwagger.class)))
8.   .build();
9.   }

3.3 添加 NotIncludeSwagger  注解

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

1.   @NotIncludeSwagger
2.   @RequestMapping( "/getPeople2")
3.   public People getPeople2(Integer id, String name, String address){
4.   People peo = new People();
5.   peo.setId(id);
6.   peo.setName(name);
7.   peo.setAddress(address);
8.   return peo;
9.   }

4 设置范围

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

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

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

1.   @Bean
2.   public Docket getDocket(){
3.   return new Docket(DocumentationType.SWAGGER_2)
4.   .apiInfo(swaggerDemoApiInfo())
5.   .select()
6.   .paths(allowPaths())
7.   .build();
8.   }
9.   private Predicate<String>  allowPaths(){
10.   return or ( (regex ("/demo/.*"));
11.   }

二、 Swagger2  常用注解

1 Api

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

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

description:描述，已过时。

1.   @RestController
2.   @RequestMapping( "/people")
3.   @Api(tags = { "mydemo"},description = "描述")
4.   public class DemoController {

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

2 ApiOperation

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

• value：接口描述
• notes：提示信息

代码示例：

@ApiOperation(value="接口描述",notes = "接口提示信息")

 

在 swagger-ui 中显示效果

3 ApiParam

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

name：参数名称

value：参数描述

required：是否是必须

public People getPeople(Integer id, @ApiParam(value=" " 姓名" ",required =  true) String name, String address)

 

swagger-ui 显示效果如下：

4 ApiModel

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

• value：名称
• description：描述

代码示例：

1.   @ApiModel(value = "人类",description = "描述")
2.   public s class People {

swagger-ui.html 效果展示

5 ApiModelProperty

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

value：描述

name：重写属性名

required：是否是必须的

example：示例内容

hidden：是否隐藏。

代码示例：

1.   @ApiModelProperty(value = "姓名",name =  "name",required =  true,example = "张三")
2.   private String  name;

swagger-ui.html 效果展示

6 ApiIgnore

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

7 ApiImplicitParam

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

name：属性名

value：描述

required：是否是必须的

paramType：属性类型

dataType：数据类型

代码示例：

1.   @PostMapping( "/getPeople")
2.   @ApiImplicitParam(name="address",value="地址",required=true,paramType="query",dataType="string")
3.   public People getPeople(Integer id, @ApiParam(value="姓名",required =  true) String
4.   name, String address){

swagger-ui.html 效果展示

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

@ApiImplicitParams(value={@ApiImplicitParam(name= "id",value = "编号",required =true),@ApiImplicitParam(name= "name",value = "姓名",required =  true)})

 

 

 

标签：常用,name,required,value,注解,Swagger,Docket,public
From： https://www.cnblogs.com/wanghengbin/p/17923749.html