在SpringMVC中集成Swagger2

为什么要使用Swagger2

  在现在的项目开发中，后端越来越多的倾向于只提供api接口，而不进行页面等的搭建，编写操作，无论是采用前后端分离的开发模式，还是给移动端提供api接口等都是如此。而在这种情况下，如何提供高质量的api文档才是最为关键的。

  以往的文档提供方式比较的粗放，就是直接由接口开发人员手动编写word文档，然后再交给移动端或前端开发人员，由他们根据接口文档来执行接口调用操作。这样的开发过程其弊端是显而易见的。其弊端主要有以下几点：

• 接口文档提交不及时，导致后台人员说做了，但是前台人员却认为没做，因为他们没有得到及时的api接口文档。

• 需求变动，导致api接口的时常变动，这在开发中是一个很常见的问题，在这种情况下，有的接口会被废弃，有的则是重新添加，有的则是有了明显的调用参数或返回值的变动，而这些变动在文档的编写上往往表现的很错乱，每个接口开发人员都在维护自己模块下的文档，而自己的那份文档本身就有很多的版本，这样在后续的api接口文档的合并中本身就会问题不断。

• api接口文档的查看与测试不方便，俗话说，一千个读者就有一千个哈姆雷特，在api文档的编写过程中，其实很多人都会无形中将自己的文档编写风格带进去，这样就会导致api接口文档的编写风格不一致，导致到前端或移动端人员拿到手后，得好好的研究，不断的去试错等。

  而Swagger就是在这样的背景下诞生的。在这里我将在SpringMVC中以集成Swagger2为例来进行说明。

在SpringMVC中集成Swagger2

引入依赖

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

添加Swagger2配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类
 * @Configuration：让Spring来加载该类配置。
 * @EnableWebMvc：启用mvc模式
 * @EnableSwagger2：启用Swagger2。
 */
@Configuration
@EnableWebMvc
@EnableSwagger2
public class Swagger2 extends WebMvcConfigurationSupport {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.扫描包地址.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring 中使用Swagger2构建RESTful APIs")
                .description("这里是描述信息")
                .termsOfServiceUrl("http://www.xxx.com")
                .license("证书")
                .licenseUrl("证书地址")
                .version("1.0")
                .build();
    }

}

让Spring加载Swagger2配置类

  在Spring的配置文件中加载Swagger2配置类。

<bean class="com.扫描包地址.swagger.Swagger2" id="swagger2Config"/>

  允许浏览器访问Swagger2的webjar静态资源。

<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>

访问Swagger2

  启动服务器，在浏览器的地址中访问如下地址：

http://localhost:8080/swagger-ui.html

  显示的结果如下：