Swagger注解

1、版本

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

2、注解

2.1、Api

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

@Api	在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。可通过选择器配置。

主要的属性

属性	描述
value	url的路径值
tag	如果设置这个值、value的值会被覆盖，可设置多个值，将根据tag分类显示api
produces	设置返回数据格式，例如, "application/json, application/xml"
consumes	设置请求数据格式，例如, "application/json, application/xml"
protocols	设置请求协议
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

2.2、ApiOperation

@ApiOperation	通常用在方法上，说明方法的作用。

主要的属性

value	url的路径值
tags	如果设置这个值、value的值会被覆盖
notes	备注
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
responseReference	指定对响应类型的引用。指定的引用可以是本地的或远程的，将按原样使用，并将覆盖任何指定的 response() 类
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
nickname	别名
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
responseHeaders	设置响应头
code	http的状态码 默认 200
extensions	扩展属性
ignoreJsonView	在解析操作和类型时忽略 JsonView 注释。

2.3、ApiParam

用于控制器请求方法的参数上。

常用属性

name	属性名称
value	属性值
defaultValue	默认值
allowableValues	取值列表
required	是否必填
access	允许从 API 文档中过滤参数。
allowMultiple	指定参数是否可以通过多次出现来接受多个值
hidden	是否隐藏
example	举例
examples	多种举例
allowEmptyValue	是否允许为空
readOnly	是否只读

2.4、ApiImplicitParams、ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam也可以定义参数.

• @ApiImplicitParams：用在请求的方法上，包含一组参数说明
• @ApiImplicitParam：对单个参数的说明
• @ApiImplicitParam中的paramType 必须要有，不然接口传递过来的是null

常用属性

name	参数名
value	参数说明
dataType	数据类型
paramType	"query" 表示参数放在哪里 · header 请求参数的获取：@RequestHeader · query 请求参数的获取：@RequestParam · path（用于restful接口） 请求参数的获取：@PathVariable · body（不常用） · form（不常用）
defaultValue	参数的默认值
required	表示参数是否必须传

2.5、ApiResponses、ApiResponse

@ApiResponses、@ApiResponse对响应码说明

2.6、ApiModel、ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性。

3、举例

@RestController
@Api(value = "annotation value", tags = "Api tag",
        produces = "application/json",consumes = "application/json")
public class AnnotationSwaggerController {

    @GetMapping("/swagger3/find_by_id/{userId}")
    @ApiOperation(value = "根据id查询查询操作")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId",value = "用户id",
                    required = true,dataType = "Long",paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(code = 404,message = "资源未找到")
    })
    public MvcResponse<UserVo> queryById(@PathVariable Long userId){
        UserVo vo = new UserVo();
        return new MvcResponse(vo);
    }

    @GetMapping("/swagger3/save")
    @ApiOperation(value = "保存操作")
    @ApiResponses({
            @ApiResponse(code = 404,message = "资源未找到")
    })
    @ApiParam(name = "inputDTO",value = "用户保存用户信息",required = true)
    public MvcResponse<Void> save(@RequestBody UserInputDTO inputDTO){
        return MvcResponse.success();
    }

}

@Data
@ApiModel("用户信息")
public class UserVo implements Serializable {
    @ApiModelProperty(value = "用户ID")
    private Long id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "邮箱")
    private String email;
}