swagger2 常用注解的使用

一、@Api  

效果：

@Api注解放在类上面，这里的value是没用的，tags表示该controller的介绍。

二 、@ApiOperation

 

效果：

@ApiOperation注解用于放在方法上面，其中value是该类的简短的叙述，notes一般是该方法的详细描述。

 

三、@ApiImplicitParam 与 @ApiImplicitParams

 

@ApiImplicitParam注解用于表明前端传入的name参数的名字，required是否为必需项，以及dataType参数类型，以及paramType传递方式（query表示使用url问号的方式传参，这种比较常用，如果使用formData的方式进行传参，那么paramType的值为 form）.

当有多个参数时，需要用@ApiImplicitParams将@ApiImplicitParam包起来

 

四、如果传递的是pojo类型的参数

 

在ui.html中

 

这里的Data Type为 Model,此时我们可以在实体类的代码中添加注解，选择我们需要在这里显示的属性。如下：

 

 

@ApiModelProperty(hidden = true)表示不需要在swagger页面进行展示，required表示该属性为必需的属性。

结果如下：

 

五、如果上传的是媒体文件类型

 

 

==========================================================================

写在最后，在使用swagger的时候可能会遇到的bug，当前后端的传递参数的名称对应上之后，后台仍然无法接收到参数，这可能是因为我们没有加上request相关的说明，如@requestParam @requestBody  required=true 等。这样会导致 从swagger.ui.html中传递过来的参数后台无法接收到。但是在正常的开发过程中我们是即使不写这几个request相关的注解，只要属性的名字可能对应上，那么后台也是可能正常接受到参数的。这也许是swagger2中隐藏的一个bug。

============================================================================

更多swagger2的使用 请参考 https://blog.xiaomo.info/2016/JavaSpringBootSwaggerUi/