Springboot系列——集成swagger2，生成API

Swagger简介

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

很多时候由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
为了解决这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。

Springboot中swagger2快速集成

1.配置pom依赖

<!--父依赖-->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.5.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<!--编码格式-->
<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
</properties>

<dependencies>

    <!--核心依赖-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    
    <!--Swagger2-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.5.0</version>
    </dependency>
    
    <!--Swagger-ui-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.5.0</version>
    </dependency>
    
    <!-- 引入web依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- 引入test测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    
    <!-- Junit 单元测试 依赖 -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
    </dependency>
    
    <!-- 引入Lombock依赖 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!--阿里fastjson-->
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.46</version>
    </dependency>
    
    <!-- Spring Boot devtools 热部署 依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
    </dependency>

    <!--quartz定时任务-->
    <dependency>
        <groupId>org.quartz-scheduler</groupId>
        <artifactId>quartz</artifactId>
        <version>2.3.0</version>
    </dependency>

    <!--Excel导入导出-->
    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi</artifactId>
        <version>3.17</version>
    </dependency>

    <dependency>
        <groupId>org.apache.poi</groupId>
        <artifactId>poi-ooxml</artifactId>
        <version>RELEASE</version>
    </dependency>

</dependencies>

<build>
    <plugins>
        <!-- SpringBoot 项目打jar包的Maven插件 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
    <!-- SpringBoot项目打包jar名称 -->
    <finalName>SpringBoot-one</finalName>
</build>

2.添加配置文件

/**
 * @author 陈永佳
 * @date 2019/6/24 13:47
 * 通过 @Configuration 注解，让Spring来加载该类配置。
 * 再通过 @EnableSwagger2 注解来启⽤Swagger2
 */
@Configuration
@EnableSwagger2
public class SpringSwaggerConfig {
    /**
     * @Author ChenYongJia
     * @Description //TODO
     * @Date  2019/6/24
     * 通过createRestApi函数创建Docket的bean之后，
     * apiInfo用来创建该API的信息，
     * select函数返回一个ApiSelectorBuilder实例用来控制那些接口暴露给swagger来展现。
     **/
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jmccms"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2构建RESTful APIs")
                .description("果果")
                .termsOfServiceUrl("https://blog.csdn.net/qq_44741038")
                .version("1.0")
                .build();
    }
}

3.编写启动类

/**
 * @author 陈永佳
 * @date 2019/6/19 9:24
 */

==@EnableSwagger2==
@SpringBootApplication
public class  SpringBootOApplication{

    /**
     * @Author ChenYongJia
     * @Description 启动类
     * @Date  2019/6/19
     * @Param
     * @return
     **/
    public static void main(String[] args) {
        SpringApplication.run(SpringBootOApplication.class, args);
    }
}

4.注：

启动类中添加 @EnableSwagger2注解，开启swagger；

对接口进行api文档注解，不进行注解也会由相关的api，但是没有接口的详细描述，只有开发人员可以看懂。

5.注解例如：

 1 @RestController
 2 @RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
 3 public class UserController {
 4     static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
 5     @ApiOperation(value="获取用户列表", notes="")
 6     @RequestMapping(value={""}, method=RequestMethod.GET)
 7     public List<User> getUserList() {
 8         List<User> r = new ArrayList<User>(users.values());
 9         return r;
10     }
11     @ApiOperation(value="创建用户", notes="根据User对象创建用户")
12     @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
13     @RequestMapping(value="", method=RequestMethod.POST)
14     public String postUser(@RequestBody User user) {
15         users.put(user.getId(), user);
16         return "success";
17     }
18     @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
19     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
20     @RequestMapping(value="/{id}", method=RequestMethod.GET)
21     public User getUser(@PathVariable Long id) {
22         return users.get(id);
23     }
24     @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
25     @ApiImplicitParams({
26             @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
27             @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
28     })
29     @RequestMapping(value="/{id}", method=RequestMethod.PUT)
30     public String putUser(@PathVariable Long id, @RequestBody User user) {
31         User u = users.get(id);
32         u.setName(user.getName());
33         u.setAge(user.getAge());
34         users.put(id, u);
35         return "success";
36     }
37     @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
38     @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
39     @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
40     public String deleteUser(@PathVariable Long id) {
41         users.remove(id);
42         return "success";
43     }
44 }