526互联

Swagger信息配置与常用注解

发布时间 2023-12-23 22:26:10作者: l_v_y_forever

转载自：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)})