Swagger (三) --------- 常用注解

你的名字 2024-04-03 08:32 86阅读 0赞

--------------------

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

<table> 
 <thead> 
  <tr> 
   <th>Swagger注解</th> 
   <th>简单说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api(tags = “xxx模块说明”)</td> 
   <td>作用在模块类上</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation(“xxx接口说明”)</td> 
   <td>作用在接口方法上</td> 
  </tr> 
  <tr> 
   <td>@ApiModel(“xxxPOJO说明”)</td> 
   <td>作用在模型类上：如VO、BO</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty(value = “xxx属性说明”,hidden = true)</td> 
   <td>作用在类方法和属性上，hidden设置为true可以隐藏该属性</td> 
  </tr> 
  <tr> 
   <td>@ApiParam(“xxx参数说明”)</td> 
   <td>作用在参数、方法和字段上，类似@ApiModelProperty</td> 
  </tr> 
 </tbody> 
</table>

我们也可以给请求的接口配置一些注释

@ApiOperation("fancy的接口")
    @PostMapping("/fancy")
    @ResponseBody
    public String fancy(@ApiParam("这个名字会被返回")String username){
        
       return username;
    }

这样的话，可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！

相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，提醒下大家在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。