swagger 总结

Swagger 常用注解说明

Swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

常用注解

@Api：修饰整个类，描述 Controller 的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口

value	字符串	可用在方法头上.参数的描述容器
notes	字符串	说明
httpMethod	字符串	请求方法

@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty

	name	字符串	实体类参数名称
	value	字符串	实体类参数值
	notes	字符串	说明
	required  	布尔值	true/false
	example 字符串  示例

@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP 响应其中 1 个描述

	code	整形	可用在@ApiResponses里
	message	字符串	错误描述
	response	类	返回结果对应的类

@ApiResponses：HTTP 响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError：发生错误返回的信息
@ApiImplicitParam：一个请求参数

name	字符串 与参数命名对应	可用在@ApiImplicitParams里
value	字符串	参数中文描述
required	布尔值	true/false
dataType	字符串	参数类型
paramType	字符串	参数请求方式:query/path
query:对应@RequestParam传递
path: 对应@PathVariable{}path传递
dataType	字符串	参数类型
dataTypeClass	类	参数对应的类
defaultValue	字符串	在api测试中默认值

@ApiImplicitParams：多个请求参数

@Api(value = "xxx", description = "xxx", tags = "xxxx")
@ApiOperation(value = "xxx", notes = "xxx", description = "xxx", method = "GET")
@ApiImplicitParam(paramType = "query", name = "xx", value = "xx", required = true, dataType = "List")
@ApiResponse(code = 200, message = "Successful", response = CommonResponse.class)
@ApiModelProperty(required = true,value = "订单id",notes = "订单id",example = "00197cc5136a495a95934b35c4b34578")

参考 ：

swagger 常用注解_xiaolyuh的专栏-CSDN博客
swagger被拦截器拦截_醉鱼的博客-CSDN博客_swagger被拦截器拦截
Swagger2 非全局、无需重复输入的Head参数（Token）配置 - 简书
配置 Swagger2 接口文档引擎 - 简书
Swagger3 注解使用（Open API 3）_StarJava_的博客-CSDN博客