Swagger集成及常用注解使用场景

环境集成

先引入相关依赖

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- 解决swagger2中guava默认版本18.0产生 The following method did not exist:FluentIterable.class -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>

Swagger2配置类

/**
 * @author: brbai
 * @create: 2019-05-15 22:07:55
 * @description: Swagger配置类
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	//读取properties配置文件中swagger.is.enable的值
    @Value("${swagger.is.enable}")
    private boolean swaggerIsEnable;

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerIsEnable)
                .apiInfo(apiInfo())
//                .useDefaultResponseMessages(false)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bhy702.jfkj.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("JFKJ-CRM 接口文档")
                .contact(new Contact("brbai","https://www.bhy702.com","baihongyuan702@163.com"))
                .description("JFKJ-CRM swagger接口文档")
                .version("1.0")
                .build();

    }
}

---

---

Swagger注解使用场景

常用注解解释：

@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面，可以单独使用
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：只能用在@ApiResponses中，用于表达一个错误的响应信息
code：数字，状态码
message：提示信息
response：抛出的异常

---

生成实体model：

@ApiModel(value = "用户model", description = "用户实体")
@Data
public class SysUserVo {

    @ApiModelProperty(value = "实体id",example = "1",required = false)
    private Integer id;

    @ApiModelProperty(value = "实体名称")
    private String name;
}

【例】生成效果：

---

常用接口注解使用

状态响应信息

@ApiResponses(value = {
       @ApiResponse(code = 0, message = "响应成功"),
       @ApiResponse(code = 200, message = "响应成功"),
       @ApiResponse(code = 401, message = "认证失败"),
       @ApiResponse(code = 403, message = "权限不足"),
       @ApiResponse(code = 404, message = "访问路径错误"),
       @ApiResponse(code = 500, message = "服务器内部错误")
})

修饰类：

@Api(tags = "用户管理", description = "系统用户管理相关接口")

修饰方法：

@ApiOperation(value = "添加用户", notes="管理员添加用户", httpMethod = "POST")

修饰参数：

• 单个普通参数

  @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "query")
  或
  @RequestMapping("/find")
    public JsonResult add(@ApiParam(name = "username", value = "用户名", required = true) @RequestParam("username") String username){
  	//.....
    }

• 单个对象参数

  @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User", paramType = "body")
  	或
  	@RequestMapping("/add")
     public JsonResult add(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user){
  		//.....
     }

• 单个数组参数
  @ApiImplicitParam(name = "userIds", value = "用户id数组", required = true, dataType = "int",allowMultiple = true)

  • 多个参数

    @ApiImplicitParams({
              @ApiImplicitParam(name = "userIds", value = "用户id数组", required = true, dataType = "int",allowMultiple = true),
              @ApiImplicitParam(name = "isAgree", value = "是否审批通过，1:通过，-1:拒绝", required = true, dataType = "int", paramType = "body"),
              @ApiImplicitParam(name = "role", value = "用户角色", required = true, dataType = "String", paramType = "body")
      })

    ---

    【注意】@ApiImplicitParam与@ApiParam修饰对象参数的区别

    @使用ApiImplicitParam文档中无对象结构：
    
    @使用ApiParam修饰对象时含对象json结构：