swagger注解详细说明

常用到的注解有：

（1）关于模型的注解：
@Api
@ApiModel
（2）关于接口的注解：
@ApiModelProperty
@ApiOperation
@ApiParam
@ApiResponse
@ApiResponses
@ResponseHeader

1. api标记

@Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。属性配置：

属性名称                     备注
value                 url的路径值
tags                  设置这个值、value的值会被覆盖
description           对api资源的描述
basePath              基本路径可以不配置
position              如果配置多个Api 想改变显示的顺序位置
produces              For example, "application/json, application/xml"
consumes              For example, "application/json, application/xml"
protocols             Possible values: http, https, ws, wss.
authorizations        高级特性认证时配置
hidden                配置为true 将在文档中隐藏

在SpringMvc中的配置如下：

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {}

2. ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(value = "Find purchase order by ID",notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",response = Order,tags = {"Pet Store"})

与Controller中的方法并列使用。属性配置：

属性名称    备注
value               url的路径值
tags                如果设置这个值、value的值会被覆盖
description         对api资源的描述
basePath            基本路径可以不配置
position            如果配置多个Api 想改变显示的顺序位置
produces            For example, "application/json, application/xml"
consumes            For example, "application/json, application/xml"
protocols           Possible values: http, https, ws, wss.
authorizations      高级特性认证时配置
hidden              配置为true 将在文档中隐藏
response            返回的对象
responseContainer   这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod  "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code                http的状态码 默认 200
extensions          扩展属性

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET)@ApiOperation(value = "Find purchase order by ID",notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",response = Order.class,tags = { "Pet Store" })public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)throws NotFoundException {Order order = storeData.get(Long.valueOf(orderId));if (null != order) {return ok(order);} else {throw new NotFoundException(404, "Order not found");}}

3. ApiParam标记

ApiParam请求属性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。
属性配置：

属性名称              备注
name             属性名称
value            属性值
defaultValue     默认属性值
allowableValues  可以不配置
required         是否属性必填
access           不过多描述
allowMultiple    默认为false
hidden           隐藏该属性
example          举例子

在SpringMvc中的配置如下：

 public ResponseEntity<Order> getOrderById(@ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)@PathVariable("orderId") String orderId)

4. ApiResponse

ApiResponse：响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。属性配置：

属性名称                备注
code                http的状态码
message             描述
response            默认响应类 Void
reference           参考ApiOperation中配置
responseHeaders     参考 ResponseHeader 属性配置说明
responseContainer   参考ApiOperation中配置

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST)@ApiOperation(value = "Place an order for a pet", response = Order.class)@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })public ResponseEntity<String> placeOrder(@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {storeData.add(order);return ok("");}

5. ApiResponses

ApiResponses：响应集配置，使用方式：

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。属性配置：

属性名称    备注
value   多个ApiResponse配置

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST)@ApiOperation(value = "Place an order for a pet", response = Order.class)@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })public ResponseEntity<String> placeOrder(@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {storeData.add(order);return ok("");}

6. ResponseHeader

响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。属性配置：

属性名称                 备注
name                响应头名称
description         头描述
response            默认响应类 Void
responseContainer   参考ApiOperation中配置

在SpringMvc中的配置如下：

@ApiModel(description = "群组")

7. 其他

@ApiImplicitParams：用在方法上包含一组参数说明；
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
name：参数代表的含义
value：参数名称
dataType：参数类型，有String/int，无用
required ：是否必要
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应；
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；
code：响应码(int型)，可自定义
message：状态码对应的响应信息
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
@ApiModelProperty：描述一个model的属性。

來源：简书
注：文中有整理和改动。

swagger注解详细说明相关推荐

java 生成并覆盖文件,基于mybatis-plus生成不被覆盖的文件并支持swagger注解
情况是这样的: 原本mybatis-plus的框架的模板是不支持swagger的注解的,需要手动写. 自己折腾了1个多小时,建立在mybatis-plus的基础上进行修改.可以选择生成文件时,不覆盖某 ...
保存系统的操作日志，通过swagger注解获取请求描述（通用版本）
版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明. 大数据系列文章目录前言系统之前没有全局的记录操作日志,只是个别单个功能记录了操作日志,这样 ...
什么是swagger以及swagger注解详解
1.什么是swagger Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言 ...
【SpringBoot】mybatis 自动生成swagger注解，及普通查询sql
1.项目结构 1.pom文件中的引入 <?xml version="1.0" encoding="UTF-8"?> <project xmln ...
【swagger】Swagger注解介绍
Swagger注解介绍 1.swagger注解 @ApiModel: 用于类,表示对类进行说明,用于参数用实体类接收 @ApiProperty:用于字段,表示对model属性的说明或者数据操作更改 @ ...
Android 自定义注解详细用法，手写Butterknife黄油刀
前言本篇文章主要讲解 Java 注解在Android中的常见用法 Java 注解(Annotation) Java 注解(Annotation)又称 Java 标注,是 JDK5.0 引入的一种注释 ...
swagger ui.html 路径,Swagger UI 详细讲解
本文章描述的是Swagger3.0的内容,与Swagger2.0内容有较大差别.接口描述在3.0中通过Swagger规范(一个JSON文件)来描述,Swagger2.0是通过在接口中提供一系列注解来描 ...
swagger注解说明_swagger2常用注解说明
原文:https://blog.csdn.net/u014231523/article/details/76522486 说明: 1.这里使用的版本:springfox-swagger2(2.4)sp ...
EJB注解详细说明1
本章内容覆盖了EJB3.0(也就是JPA)实体的注解规范以及hibernate特有的扩展. 现在EJB3实体Bean是纯粹的POJO.实际上这表达了和Hibernate持久化实体对象同样的概念. 它们 ...
Swagger 注解使用
一.实体类配置 1.新建一个实体类 @ApiModel("用户实体") public class User {@ApiModelProperty("姓名")pu ...

swagger注解详细说明

常用到的注解有：

1. api标记

2. ApiOperation标记

3. ApiParam标记

4. ApiResponse

5. ApiResponses

6. ResponseHeader

7. 其他

swagger注解详细说明相关推荐

最新文章

热门文章

swagger注解 详细说明

常用到的注解有：

1. api标记

2. ApiOperation标记

3. ApiParam标记

4. ApiResponse

5. ApiResponses

6. ResponseHeader

7. 其他

swagger注解 详细说明相关推荐

最新文章

热门文章

swagger注解详细说明

swagger注解详细说明相关推荐