Swagger信息配置与常用注解

转载自：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","xxx@163.com"))
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)})