SpringBoot + Swagger2 构建API文档

先贴效果

• 右上角可以选择分组，每个分组下可以设标签管理api
• 每个api可以直接测试

1. maven dependency

新建maven项目，这里使用的是idea的Spring Initializr，勾选web依赖，就快速构建了SpringBoot项目，有了tomcat和发布RESTful API能力。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 配置swagger2

主要是构建Docket Bean，SwaggerConfig.java代码如下：

@Configuration
@EnableSwagger2
@Profile({"dev", "test"}) 
public class SwaggerConfig {
    @Bean
    public Docket apiGroup1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Group 1").tags(
                        new Tag("标签一", "描述")
                        , new Tag("标签二", "描述")
                )
                .apiInfo(this.getApiInfo("接口", "接口"))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(or(regex("/demo.*")))
                .build();
    }

    private ApiInfo getApiInfo(String title, String desc) {
        return new ApiInfo(
                "XX系统 " + title + " API",
                desc + " API文档",
                "1.0",
                "",
                new Contact("联系我们", "", "mail@mail.com"),
                "license",
                "licenseUrl",
                new ArrayList<>());
    }

• @Profile({"dev", "test"}) 指明了只在dev和test profile运行时启用swagger，如实际项目运行prod profile时就不启用swagger
• .groupName可以不设，默认会有一个default的分组，实际项目中模块比较多，这个分组会比较实用，UI中右上角可以切换分组。 分组可以把多个tag组织在一起，通常是一个controler对应一个tag。需要加一个分组可以再建一个Docket Bean。

3. 新增Controller

package com.bq.demo.test;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.apache.catalina.User;
import org.springframework.web.bind.annotation.*;

@Api(value = "/demo/test", tags = "标签一")
@RestController
@RequestMapping("/demo/test")
public class TestSwaggerController {
    @ApiOperation(value = "显示helloWorld", notes = "显示helloWorld")
    @GetMapping("/helloWorld")
    public Object showInfo() {
        return "hello world";
    }

    @ApiOperation(value = "添加用户信息", notes = "添加用户信息")
    @ApiImplicitParam(name = "user", value = "User", required = true, dataType = "User")
    @PostMapping("/addUser")
    public Object addUser(@RequestBody User user) {
        return "success";
    }
}

• 注意@Api中tags和上面group中的对应
• 标签二的Controller代码只是复制了一份，改了下@Api和@RequestMapping映射
• 打开 http://localhost:8080/swagger-ui.html 测试