SpringBoot 使用 Swagger 插件生成API

一、swagger简介

引用官方说明：

Swagger open source and pro tools have helped millions of API developers, teams, and organizations deliver great APIs.

二、SpringBoot项目引入swagger插件

引入插件依赖，以Gradle为例：

  compile "io.springfox:springfox-swagger2:2.9.2"
  compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

springfox-swagger为针对spring的swagger插件，swagger-ui为界面工具。

三、swagger插件常用注解(annotation)说明

1. 接口 class 注解

＠Api：接口类说明

参数说明：
value：dtring，接口描述
tags：数组，接口标签

2. 接口 method 注解

@ApiOperation：接口方法说明

参数说明：
value：string,接口名
notes：string，接口描述
httpMethod： string,　接口类型，GET/POST/PATH/PUT/DELETE等
response：Class,返回参数类型
responseContainer：string, 返回容器，如list

@ApiImplicitParam:接口参数说明

参数说明：
name: string, 参数名称
value：string,参数标题
defaultVale: string, 默认值
required：true/false，是否必须
paramType：string, 参数类型，head/path/query等
dataType: string, 参数数据类型，string/int等

@ApiImplicitParams:多个@ApiImplicitParam

3. 接口 param 注解

@ApiParam：接口参数说明

参数说明：与@ApiImplicitParam基本一致

4. ViewModel注解

@ApiModel：模型注解

参数说明：
value: string, 模型名称
description: string,　模型描述

@ApiModelProperty：模型属性注解

参数说明
name: string, 参数名称
value: string, 参数标题
notes: string, 参数描述
dataType: string, 数据类型
required: boolean, 是否必须
example: strign, 示例

5. 通用注解

@ApiIgnore：忽略

四、插件使用

1. 配置插件

新建SwaggerConfig类，使用 @Configuration 定义为spring配置类，@EnableSwagger2 启用Swagger插件。

class SwaggerConfig:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .title("人员服务ＡＰＩ文档")
                .termsOfServiceUrl("https://baidu.com")
                .description("人员相关业务模块ＡＰＩ说明文档")
                .version("v１．０")
                .build();
    }
}

2. 添加注解

编写一个Restful API接口：

@RestController
@RequestMapping(value = "/user")
public class DemoController {

    @GetMapping(value = "/{userId}")
    public User detail (@PathVariable String userId) {
        return new User(){{
            setUserId(userId);
            setName("jack");
            setAge(18);
        }};
    }

    @GetMapping(value = "/role")
    public List<User> roleUser (String roleId) {
        return new ArrayList<>();
    }

    @PostMapping
    public ResponseEntity<String> create (User user) {
        return new ResponseEntity<>("user created", HttpStatus.OK);
    }

    @PutMapping
    public ResponseEntity<String> update (User user) {
        return new ResponseEntity<>("user updated", HttpStatus.OK);
    }

    @DeleteMapping(value = "/{userId}")
    public ResponseEntity<String> delete (@PathVariable String userId) {
        return new ResponseEntity<>("user deleted, user's primary key is: " + userId, HttpStatus.OK);
    }
}

为 Controller 类添加 Swagger 注解：

    @ApiOperation(value = "获取用户", notes = "获取用户详细信息")
    @ApiImplicitParam(name = "userId", value = "user's primary key", required = true)

    @GetMapping(value = "/{userId}")
    public User detail (@PathVariable String userId) {
        return new User(){{
            setUserId(userId);
            setName("jack");
            setAge(18);
        }};
    }

为Model添加Swagger注解：

@ApiModel(value = "user model")

@Data
public class User {
    /**
     * user's primary key
     */
    @ApiModelProperty(value = "用户id")
    private String userId;

    /**
     * user's name
     */
    @ApiModelProperty(value = "用户名")
    private String name;

    /**
     * user's age
     */
    @ApiModelProperty(value = "用户年龄")
    private int age;

    /**
     * user's birthday
     */
    @ApiModelProperty(value = "生日")
    private Date birthday;

    /**
     * user's role
     */
    @ApiModelProperty(value = "角色")
    private String role;

    /**
     * user's department
     */
    @ApiModelProperty(value = "部门")
    private String department;
}

3. 查看文档

启动Application类，访问 http://localhost:8080/swagger-ui.html查看API文档：

4. 生产环境禁用

API文档在生产环境不可访问，可通过为SwaggerConfig类添加prifile标签实现：

@Configuration
@EnableSwagger2
@Profile(value = {"test", "dev"})
public class SwaggerConfig {

    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .title("user api document")
                .description("the api document for user, department and role")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("v1.0.0")
                .build();
    }

}

备注：

demo 工程仓库地址：https://gitee.com/louie-sun/boot-swagger