Spring Boot使用Swagger生成API手册

现在越来越多的应用都采用restful风格的开发模式来构建API，这样也有利于实现前后端分离，前端进行数据展示，后端提供数据，前后端之间通过json的格式来进行数据传递。这时候前后端之间的交流就只有通过API来进行了，但是随着发布的API越来越多交流与测试就成了一个很麻烦的事情。
为了解决这类问题业界也提供各种解决方案，我们这里选用Swagger技术来解决这个问题，关于Swagger的介绍请参见官网Swagger，当然Swagger提供了java实现，因为我采用的spring boot所以选用springfox这个开源实现来集成Swagger。
软件环境

spring boot 2.0

首先需要引入依赖，我们看pom文件

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

下一步我们就要创建Swagger的配置类，参见以下代码

/**
 * @author chengjian
 * @date 2018/2/19
 **/

@Configuration
@EnableSwagger2 //Enable swagger 2.0 spec
@ComponentScan(basePackageClasses = {
        UserController.class
})
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("user-api")
                .apiInfo(apiInfo())
                .select()
                .paths(userPaths())
                .build();
    }
    private Predicate<String> userPaths() {
        return regex("/user.*");
    }
    /**
     * api 页面简介
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX系统API")
                .description("提供相应的数据调用api，仅供测试")
                .version("1.0")
                .build();
    }

}

代码很简单，当然这只是最简单的Swagger配置
@EnableSwagger2 //Enable swagger 2.0 spec 这个注解说明我们采用的是最新的Swagger2版本
@ComponentScan(basePackageClasses = {UserController.class}
这个注解表明我们将UserController这个类纳入Swagger管理，如果有多个类要使用Swagger那么需要加入多个累并以逗号分隔。
addResourceHandlers()这个方法是定义了Swagger页面的映射路径，如果不配置就没法跳转到相应的Swagger页面。
userApi()和userPaths()方法就定义了UserController具体的配置信息。
apiInfo()这个方法定义了Swagger相应的描述信息。
这样我们就完成了Swagger的基础配置
完成了Swagger的配置后我们需要定一个一个Controller来实现Swagger的跳转映射，因此我们创建了一个Controller

package com.spring.common.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

@Controller
public class HomeController {
    @RequestMapping("/")
    public String home() {
        System.out.println("homecontroller");
        return "redirect:swagger-ui.html";
    }
}

这里我们就定义了Swagger的映射和跳转。

至此我们就完成了Swagger的基本使用，其实Swagger包含了很多的使用方法，例如安全之类的可以参见springfox的官方文档springfox。
这里的简单的配置我也有代码实现，可以参考我的代码spring