SpringBoot2.0学习之集成Swagger2

SpringBoot2.0学习之集成Swagger2, 放弃原有接口文档

1. 为什么要使用Swagger2?

Swagger2可以在更新代码的同时更新接口文档，不会出现代码更新了好几个版本了，但是接口文档从来没更新过，导致后期维护的困难。我有一个同学刚入职的一家公司，代码和接口文档根本就对不上，导致他现在根本不敢轻易动代码。

2. 如何集成Swagger2.

1. 在pom.xml中引入相关依赖

		<!--swagger2-->
        <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>

2. 编写Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .apiInfo(new ApiInfoBuilder()
                        .title("集成使用Swagger2")
                        .description("这里是描述信息")
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qf.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

3. 开始给接口写描述信息，常用注解如下：

@Api：用于描述类

@ApiOperation：用于描述接口方法

@ApiImplicitParam：写在方法上，用于描述参数信息

@ApiImplicitParams：一组参数信息，可以放多个@ApiImplicitParam

@ApiParam：写在参数上，用于描述参数信息

@ApiModel：写在类上，用于描述实体信息

@ApiModelProperty：写在属性上，用于描述实体属性信息

测试代码如下：

controller：

@Api(tags = "用户管理相关接口")
@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "添加一个用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = true, paramType = "query", dataType = "Integer")
    })
    @RequestMapping(value = "/insert", method = RequestMethod.POST)
    public String insert(@RequestParam("name") String name, Integer age) {
        userService.insert(name, age);
        return "success";
    }

    @ApiOperation(value = "分页查询用户列表")
    @RequestMapping(value = "selectList", method = RequestMethod.POST)
    public PageInfo<User> selectList(@ApiParam(value = "页数") Integer page, @ApiParam(value = "每页记录数")Integer pageSize) {
        return userService.selectList(page, pageSize);
    }

    @ApiOperation(value = "删除一个用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path")
    @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
    public Integer delete(@PathVariable Integer id) {
        return id;
    }

}

实体类

@Data
@ApiModel(description = "用户实体信息")
public class User {

    @ApiModelProperty("用户ID")
    private Integer id;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;

    @ApiModelProperty("地址")
    private String address;
}

3. 访问http://localhost:8080/swagger-ui.html 结果如下：

Ps: 如果需要分组的话，需要配置多个Docket Bean, 通过groupName进行分组，例如：

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .groupName("分组1")
                .apiInfo(new ApiInfoBuilder()
                        .title("集成使用Swagger2")
                        .description("这里是描述信息")
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qf.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket groupApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .groupName("分组2")
                .apiInfo(new ApiInfoBuilder()
                        .title("集成使用Swagger2")
                        .description("这里是描述信息")
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qf.demo.group2"))
                .paths(PathSelectors.any())
                .build();
    }
}

如图：

---

一个人如果知道自己为什么而活，就可以忍受任何一种生活 ---- 尼采