Swagger常用注解

Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

类注解

@Api

标识这个类是swagger的资源

• tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性
• description：可描述描述该类作用

@ApiModel

对类进行说明，用于参数用实体类接收

方法注解

@ApiImplicitParam

单独的请求参数

• name：参数名
• value：参数的具体意义，作用
• required：参数是否必填
• dataType：参数的数据类型
• paramType：查询参数类型，如下几种
  • path：以地址的形式提交数据
  • query：直接跟参数完成自动映射赋值
  • body：以流的形式提交 仅支持POST
  • header：参数在request headers 里边提交
  • form：以form表单的形式提交 仅支持POST
• 注意事项：paramType和@RequestBody有冲突，会出现Body Missing错误，去掉paramType就行了。

@ApiImplicitParams

多个包含@ApiImplicitParam

	@ApiImplicitParams({
			@ApiImplicitParam(name = "hospitalId", value = "互联网医院ID"),
			@ApiImplicitParam(name = "status", value = "状态：1-启用 2-停用") 
			})

@ApiModelProperty

对model属性的说明

@ApiModel(value = "User", description = "用户")

@ApiOperation

一个http请求的操作

 @ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")

@ApiResponse

用于方法，描述操作的可能响应。

@ApiResponses({@ApiResponse(code = HttpServletResponse.SC_NOT_FOUND, message = "404 Not Found")})

@ApiResponses

用于方法，一个允许多个ApiResponse对象列表的包装器。

@ApiResponses(value = { 
            @ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"),
            @ApiResponse(code = 500, message = "403:没有权限"),
            @ApiResponse(code = 500, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")})`

@ApiParam

用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）

public DtoResponse<DetailVO> detail(
            @ApiParam(required = true, name = "goodsId", value = "商品id") @PathVariable(value = "goodsId") Integer goodsId) {

@Authorization

声明要在资源或操作上使用的授权方案。

@AuthorizationScope

介绍一个OAuth2授权范围

@ResponseHeader

响应头设置，使用方法。

本文参考https://blog.csdn.net/java_yes/article/details/79183804?spm=1001.2014.3001.5506