【Swagger】常用注解及具体实例（超全） |
您所在的位置：网站首页 › java注解详解 › 【Swagger】常用注解及具体实例（超全） |
【Swagger】常用注解及具体实例（超全）
|
在上一篇我们详细的介绍了使用 Swagger 时需要做的配置，现在已经能得到一个我们自己想要的页面了
但是，这也看不明白啊。。。接口连个中文说明都没有。。。所以，Swagger 提供了很多注解，就是让我们去为每个类、每个接口/参数、每个Model 写解释说明的。 1.用于类的注解 @Api：资源描述标识这个类是 Swagger 的资源， @Api(tags = "商户相关接口") @RestController @RequestMapping("/merchants") public class MerchantsController可以设置的属性如下：
values：字符串；说明该类的作用，在类旁边的小字显示 tags：字符串；标签（也可理解成分类），会替换 Controller 名称；当多个 Controller 的 tags 相同时，它们的方法会在一起显示
consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json protocols：字符串；标识当前的请求支持的协议，例如：http、https、ws hidden：true/false；隐藏整个 Controller，作用与 @ApiIgnore 相似，但没有 @ApiIgnore 功能强大 @ApiIgnore：资源过滤有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解另一种是在 Docket 上增加筛选。两种方式的区别是，Docket 配置的规则，可以对多个接口器过滤作用，而 @ApiIgnore 只能作用于单个接口。 关于 Docket 上增加筛选请看上一篇…
如果想在文档中屏蔽掉删除用户的接口（user/delete），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。 2.用于方法的注解 @ApiOperation：方法描述 @ApiOperation(value = "创建商户", notes = "开发中") public Response createMerchants可以设置的属性如下：
value：字符串；方法摘要，在路径旁显示 note：字符串；方法详细描述 tags：字符串数组；对方法进行分类，一个方法可以有多个分类
response：Class；设置当前请求的返回值类型，String.class；会覆盖自动识别的返回类型，一般用不上 responseContainer：字符串；说明包装的容器，默认情况下，有效值为 List、Set、Map；在定义通用 Response 后，一般用不上 httpMethod：字符串；指定请求方式，比如 GET、POST、PUT consumes：字符串；指定处理请求的提交内容类型(Content-Type)，例如 application/json produces：字符串；指定返回的内容类型，即仅当请求头的 Accept 类型中包含该指定类型才返回，例如:application/json @ApiImplicitParam(s)：参数描述参数描述，可用在方法头。 ApiImplicitParams 只有一个属性 ApiImplicitParam[] value(); 是 ApiImplicitParam 的数组，比如 @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "商户ID") }) @GetMapping("/{id}") public Response getMerchantsInfo(@PathVariable Integer id) { return null; }所以，来看看 @ApiImplicitParam 有哪些属性：
参数描述，用在每个参数前面，比如 @PostMapping("/create") // 注：这里如果使用 @ApiImplicitParam 会出现无法识别的问题 public Response createMerchants( @ApiParam(name = "request", value = "创建商户请求对象") @RequestBody CreateMerchantsRequest request)@ApiParam 的可以设置的属性如下：
关于 @ApiImplicitParam 和 @ApiParm 它俩都能为方法的请求参数做注释，区别有： @ApiImplicitParam 可以在方法前使用，而 @ApiParm 只能在参数前使用@ApiImplicitParam 提供的可设置属性更多，特别是 paramType 很关键对于 @RequestBody 标识的 Json 字符串，不能使用 @ApiImplicitParam，会出现无法识别的情况 方案一：通过 @ApiParm 对 @RequestBody 的参数进行说明方案二：直接不对该参数使用注解，将注释的任务交给实体类（@ApiModel）另外，两者是可以混搭使用的，一般推荐使用 @ApiImplicitParam(s)，但是注意 @RequestBody 的情况。 @ApiResponse(s)跟上面 @ApiImplicitParam(s) 一样，@ApiResponses 也是只有唯一个属性ApiResponse[] value(); @ApiResponses({ @ApiResponse(code = 1, message = "非HTTP状态码，Response code字段值，描述：成功，返回该商户ID"), @ApiResponse(code = 0, message = "非HTTP状态码，Response code字段值，描述：失败") }) @PostMapping("/create") public Response createMerchants下面来看看 @ApiResponse 有哪些属性
用于请求类或者响应类上，表示一个返回响应数据的信息 @ApiModel("创建商户的请求对象") @Data @AllArgsConstructor @NoArgsConstructor public class CreateMerchantsRequest@ApiModel 可以设置的属性有：
ApiModelProperty 可以设置的属性有：
注：下面的示例代码取自我曾经写过的一个项目，只截取了部分 Swagger 相关代码。 @Api(tags = "商户相关接口") @Slf4j @RestController @RequestMapping("/merchants") public class MerchantsController { @ApiOperation(value = "创建商户", notes = "开发中") @ApiResponses({ @ApiResponse(code = 1, message = "非HTTP状态码，Response code字段值，描述：成功，返回该商户ID"), @ApiResponse(code = 0, message = "非HTTP状态码，Response code字段值，描述：失败") }) @PostMapping("/create") public Response createMerchants( @ApiParam(name = "request", value = "创建商户请求对象", required = true) @RequestBody CreateMerchantsRequest request) { return null; } @ApiOperation("获取商户信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "商户ID") }) @ApiResponses({ @ApiResponse(code = 1, message = "非HTTP状态码，Response code字段值，描述：成功", response = Merchants.class), @ApiResponse(code = 0, message = "非HTTP状态码，Response code字段值，描述：失败") }) @GetMapping("/{id}") public Response getMerchantsInfo(@PathVariable Integer id) { return null; } } @ApiModel("创建商户的请求对象") @Data @AllArgsConstructor @NoArgsConstructor public class CreateMerchantsRequest { @ApiModelProperty("商户名") private String name; @ApiModelProperty("商户logo的URL") private String logoUrl; @ApiModelProperty("营业执照URL") private String businessLicenseUrl; @ApiModelProperty("联系电话") private String phone; @ApiModelProperty("地址") private String address; }
包括配置的完整代码我放到 GitHub 上了，点击这里跳转… |
【本文地址】