spring boot2.0集成swagger2

什么是swagger2？
接口文档生成工具，解决前后端分离开发，文档对接的痛点！

主要使用：swagger editor，swagger ui
踩坑：从Spring-boot2.0以上在集成swagger后，配置WebConfig时不要extends WebMvcConfigurationSupport，需要修改为最新的implements WebMvcConfigurer，不然访问swagger-ui.html时读取不到swagger-ui的静态资源文件。

1、 添加依赖
注意：springboot2.0x，这里我使用的是swagger2的2.8.0版本。

    io.springfox
    springfox-swagger2
    2.8.0


    io.springfox
    springfox-swagger-ui
    2.8.0

2、 启动类加入注解

@EnableSwagger2

3、设置初始化配置类

package com.xxx.xx.data.center.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;


 /**
     * 指定文档扫描路径
     * @return
     */
    @Bean
    public Docket createRestApi() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List pars = new ArrayList();
        tokenPar.name("access_token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bosssoft.gp.data.center.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    /**
     * 文档基本信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXXXXX数据交换中心")
                .description("数据交换中心")
                .version("1.0")
                .build();
    }
}

4、映射配置类，注意要实现 WebMvcConfigurer

package com.xxx.xx.data.center.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 *  swagger2
 *  将jar包中的静态资源映射
 */
@Configuration
public class WebMvcConfiguration implements WebMvcConfigurer {

    @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/");

    }

}

5、配置文件设置Swagger2页面地址：

注意：swagger2不需要加入项目路径：

###swagger2页面
eureka.instance.status-page-url=http://127.0.0.1:7007/swagger-ui.html

6、页面展示
6.1 查看注册中心注册的实例

6.2 查看文档

额外说明
前面提到配置项：

1）WebMvcConfiguration

说白了，就是将引入的jar包的相关静态资源映射到项目下

2) SwaggerConfiguration

swagger的方便之处就是，通过页面可以获取接口参数，调用接口，响应数据，很类似于postman！

这里设置了一个token参数，表示调用接口需要在header上传入，而不是通过在controller使用@Api引入。
效果如图：

3）其他声明：
关于在配置项我们设置的扫描包问题

一般情况下，都是切入到controller，
对于不需要加入在页面上展示的接口，使用@ApiIgnore
效果如图：

对于需要引入文档的

当然。这个@ApiOperation有很多个参数，这里给出
主要属性有access、accessMode、allowableValues、allowEmptyValue(是否允许为空)、dataType(数据类型)、example(示例)、hidden(是否隐藏)、name(名称)、notes、required(是否必需)、value(说明)等。