Swagger注解说明

Swagger注解说明

• 环境：swagger 2.7.0

前言

使用swagger也有一段时间了，对于注解还是很混乱，这里做个记录，方便后续查阅。

注解

swagger的注解都在swagger-annotations中，当前版本总共27个注解。

<dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
      <version>1.5.13</version>
      <scope>compile</scope>
</dependency>

现在逐一查看各个注解及使用。

@Api

作用于class或interface上（推荐定义在接口上），说明该接口的作用。

@Api(tags = {"数据接口"}, description = "推荐系统")
public interface DataCollectControllerApi {}

效果：

@ApiOperation

作用于方法上

@ApiOperation(value = "查询用户行为", notes = "查询用户行为数据")
@PostMapping(value = "/behavior")
@ResponseBody
    ResultBean<PageInfo> queryUserBehaviorRecord(@RequestBody UserBehaviorReqDTO userBehaviorReqDTO);

效果：

@ApiImplicitParams和@ApiImplicitParam（不建议使用）

作用于方法上，但是不建议使用（原因：This is the only way to define parameters when using Servlets or other non-JAX-RS* environments），建议使用@ApiParam

@ApiOperation(value = "查询用户", notes = "查询用户信息")
   @ApiImplicitParams({
           @ApiImplicitParam(name = "userId", value = "用户id", paramType = "query", dataType = "int"),
           @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", dataType = "string")
   })
   @PostMapping(value = "/user")
   @ResponseBody
   ResultBean queryUserInfo(@RequestParam("userId") Integer userId,
                    @RequestParam("userName") String userName);

• name：参数名称，即下图的Parameter列

• value：参数描述，即下图的Description列

• paramType：参数类型，这里支持5种query,body,path,form,header，这里常用query和body。

  body表示该参数为json。

• paramType：参数数据类型，目前只支持基本数据类型，int，float，long等

效果：

@ApiParam

作用于方法和参数上（只有一个参数时可以在方法上使用，但通常都会有多个参数，所以建议在参数上使用）

@ApiOperation(value = "查询用户", notes = "查询用户信息")
@PostMapping(value = "/user")
@ResponseBody
ResultBean queryUserInfo(
            @ApiParam(name = "userId", value = "用户id", type = "Integer")
            @RequestParam("userId") Integer userId,
            @ApiParam(name = "userName", value = "用户名称", type = "String")
            @RequestParam("userName") String userName);

• name：参数名称，即下图的Parameter列

• value：参数描述，即下图的Description列

• type：参数数据类型，即下图的Data Type列。可以忽略，swagger会根据SpringMVC中的注解（RequestParam,RequestBody）自动匹配参数类型（Parameter Type列）和参数数据类型（Data Type列）。如下图，参数使用@RequestParam，则Parameter Type为query，Data Type为对应参数类型；

  参数使用@RequestBody，则Parameter Type为body，Data Type为对应参数类型；

  

效果：

@ApiResponses和@ApiResponse

作用于方法上，一般用于描述错误的响应信息。@ApiResponses用户描述一组错误响应。@ApiResponse用户描述具体的错误响应。

@ApiOperation(value = "查询用户", notes = "查询用户信息")
@PostMapping(value = "/user")
@ResponseBody
@ApiResponses({
    @ApiResponse(code = 1001, message = "用户参数为空",responseHeaders = {
 		@ResponseHeader(name = "header-1", description = "header-1描述", response = String.class),
        @ResponseHeader(name = "header-2", description = "header-2描述", response = Integer.class),
        @ResponseHeader(name = "header-3", description = "header-3描述", response = ResultBean.class)
      	}),
     @ApiResponse(code = 1002, message = "用户不存在", response = ResultBean.class),
    })
ResultBean queryUserInfo(
            @ApiParam(name = "userId", value = "用户id")
            @RequestBody Integer userId,
            @ApiParam(name = "userName", value = "用户名称")
            @RequestParam("userName") String userName);

• code：返回码，对应HTTP Status Code列
• message：返回码描述，对应Reason列
• response：返回值类型，对应Response Model列
• responseHeaders：返回值头信息，使用@ResponseHeader对返回值头的描述
  • name：响应头名称
  • description：响应头描述
  • response：响应头返回值类型

使用@ApiResponse时，如果同时使用response属性和responseHeaders属性，responseHeaders会失效（已测试）。另外，使用responseHeaders时，在使用@ResponseHeader时，ResponseHeader中的属性response使用类类型无效（已测试），默认为string

效果：

@ResponseHeader

ApiKeyAuthDefinition

ApiModel

ApiModelProperty

Authorization

AuthorizationScope

BasicAuthDefinition

Contact

Example

ExampleProperty

Extension

ExtensionProperty

ExternalDocs

Info

License

OAuth2Definition

Scope

SecurityDefinition

SwaggerDefinition

Tage

常用模版

参考

• https://my.oschina.net/zzuqiang/blog/793606 swagger注解类使用说明
• http://www.cnblogs.com/softidea/p/6251249.html Swagger使用