springboot,springmvc整合swagger

1.Springboot整合Swagger2

1.1.pom加swagger依赖

<dependency>

         <groupId>io.springfox</groupId>

         <artifactId>springfox-swagger2</artifactId>

         <version>2.9.2</version>

      </dependency>

      <!-- <dependency>

         io.springfox

         springfox-swagger-ui

         2.9.2

      -->

      <dependency>

            <groupId>com.github.xiaoymin</groupId>

            <artifactId>swagger-bootstrap-ui</artifactId>

            <version>1.9.0</version>

        </dependency>

      <dependency>

          <groupId>io.swagger.core.v3</groupId>

          <artifactId>swagger-annotations</artifactId>

          <version>2.0.8</version>

      </dependency>

        <dependency>

          <groupId>io.swagger.core.v3</groupId>

          <artifactId>swagger-models</artifactId>

          <version>2.0.8</version>

</dependency>

1.2.添加swagger配置类

@Configuration

@EnableSwagger2

@EnableSwaggerBootstrapUI

//@ConditionalOnExpression("${swagger.enable:true}")

public class Swagger2 {

//    @Override 

//    public voidaddResourceHandlers(ResourceHandlerRegistry registry) { 

//       registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/") 

//        registry.addResourceHandler("/webjars*").addResourceLocations("classpath:/META-INF/resources/webjars/") 

//    } 

   @Value("${swagger.enable:true}")

   private String enable

   @Value("${swagger.basePackage}")

   private String basePackage

   @Bean

   public Docket createRestApi()

{

      Predicateselector= PathSelectors. none ()

      if ("true".equals(enable)) {

         selector=PathSelectors. any ()

      }

      //定义全局参数

       Listpars = new ArrayList<>()

          ParameterBuildertoken = new ParameterBuilder()

          token.name("token").description("token").modelRef( new ModelRef("string")).parameterType("header").required( false ).build()

          pars.add(token.build())

      return new Docket(DocumentationType. SWAGGER_2 )

            .globalOperationParameters(pars) // 全局参数

            .groupName("demo01")//指定分组

            .apiInfo(apiInfo())

            .select()

            .apis(RequestHandlerSelectors. basePackage (basePackage))

//          .paths(PathSelectors.any())

            .paths(selector)

            .build()

   }

   private ApiInfo apiInfo() {

      return new ApiInfoBuilder()

            .title("SpringBoot测试使用 Swagger2 构建RESTful API")

            .description("springboot demo 接口文档")

            .version("1.0")

            .build()

   }

}

1.3.加上swagger启用禁用开关

新建application.properties文件

#swagger启用禁用标识true：启用

swagger.enable=true

#swagger扫描需生成文档的包路径

swagger.basePackage=com.tjc.springbootDemo.controller

1.4.Swagger具体注释用法

https://blog.csdn.net/xiaojin21cen/article/details/78654652

1.5本地访问swagger文档

访问原生swagger地址： http://localhost:8080/swagger-ui.html#/

访问bootStrap-swagger地址： http://localhost:8080/ doc.html

访问json文件数据地址： http://localhost:8083/v2/api-docs

1.6.在线访问swagger接口

https://www.cnblogs.com/vipstone/p/9841716.html

1.7.demo源码访问地址

https://gitee.com/JasonTran/swagger2-springbootDemo.git

2.Springmvc整合Swagger2

2.1.pom加依赖

<!-- swagger -->

      <dependency>

          <groupId>com.fasterxml.jackson.core</groupId>

          <artifactId>jackson-annotations</artifactId>

          <version>2.9.9</version>

      </dependency>

      <dependency>

          <groupId>com.fasterxml.jackson.core</groupId>

          <artifactId>jackson-core</artifactId>

          <version>2.9.9</version>

      </dependency>

      <dependency>

          <groupId>com.fasterxml.jackson.core</groupId>

          <artifactId>jackson-databind</artifactId>

          <version>2.9.9</version>

      </dependency>

       <dependency>

         <groupId>io.springfox</groupId>

         <artifactId>springfox-swagger2</artifactId>

         <version>2.9.2</version>

      </dependency>

      <!-- <dependency>

         io.springfox

         springfox-swagger-ui

         2.7.0

      -->

      <dependency>

            <groupId>com.github.xiaoymin</groupId>

            <artifactId>swagger-bootstrap-ui</artifactId>

            <version>1.9.0</version>

        </dependency>

      <dependency>

          <groupId>io.swagger.core.v3</groupId>

          <artifactId>swagger-annotations</artifactId>

          <version>2.0.8</version>

      </dependency>

        <dependency>

          <groupId>io.swagger.core.v3</groupId>

          <artifactId>swagger-models</artifactId>

          <version>2.0.8</version>

2.2.添加swagger配置类

@Configuration

@EnableSwagger2

@EnableWebMvc

@EnableSwaggerBootstrapUI

@PropertySource(value="classpath:swagger.properties")

public class Swagger2 {

   @Value("${swagger.enable:true}")

   private String enable

   @Value("${swagger.basePackage}")

   private String basePackage

   @Bean

   public Docket createRestApi()

{

      Predicateselector= PathSelectors. none ()

      //启用swagger

      if ("true".equals(enable)) {

         selector=PathSelectors. any ()

      }

//    //定义全局参数

//    List pars = new ArrayList()

//        ParameterBuilder token = newParameterBuilder()

//       token.name("token").description("token").modelRef(newModelRef("string")).parameterType("header").required(false).build()

//        pars.add(token.build())

      return new Docket(DocumentationType. SWAGGER_2 )

//          .globalOperationParameters(pars)//全局参数

            .groupName("demo01")//指定分组

            .apiInfo(apiInfo())

            .select()

            .apis(RequestHandlerSelectors. basePackage (basePackage))

//          .paths(PathSelectors.any())

            .paths(selector)

            .build()

   }

   private ApiInfo apiInfo() {

      return new ApiInfoBuilder()

            .title("SpringMvc测试使用 Swagger2 构建RESTful API")

            .description("springmvc demo 接口文档")

            .version("1.0")

            .build()

   }

}

2.3. 创建swagger.properties文件

#swagger启用禁用标识true：启用

swagger.enable=true

#swagger扫描需生成文档的包路径

swagger.basePackage=com.tjc.springmvcDemo.controller

2.4.springmvc初始化文件添加扫包配置

<!-- 开启springmvc注解 -->

    <mvc:annotation-driven/>

    <mvc:default-servlet-handler/>

   <context:component-scanbase-package= "com.tjc.springmvcDemo.controller" />

  <!-- 添加配置文件 -->

  <context:property-placeholderlocation= "classpath:swagger.properties" />

   <context:component-scanbase-package= "com.tjc.springmvcDemo.config.swagger" />

2.5.Swagger具体注释用法

https://blog.csdn.net/xiaojin21cen/article/details/78654652

2.6.在线访问swagger接口

https://www.cnblogs.com/vipstone/p/9841716.html

2.7.demo源码访问地址

https://gitee.com/JasonTran/swagger2-springmvcDemo.git

3.问题整理

3.1.项目中拦截器，过滤器拦截了swagger路径

解决方案：剔除/swagger-resources，/webjars/，/v2/，/doc.html/等路径

.excludePathPatterns("/swagger-resources/**","/webjars/**","/v2/**","/doc.html/**")

3.2. guava-${version}.jar包冲突

解决方案：在maven仓库查找最新guava jar包

3.3.分布式聚合文档结合eureka注册中心发现服务，zuul解决浏览器跨域，通过调用swagger的/v2/doc-api接口获取文档json数据实现文档聚合管理

非简单请求在发送真正的请求前会发送一次Preflight Request，接收一个Preflight Response

解决办法： requestMatchers(CorsUtils::isPreFlightRequest).permitAll()的作用是将PreflightRequest不做拦截。

由于swagger依赖的jar包guava和项目中其他依赖产生的冲突。

解决办法：去掉冲突或者添加统一的guava。比如去掉mybatis的gennerator。或者guava15.0 添加到 pom.xml 中

和spring-security配置有关

解决办法：.antMatchers("/v2/api-docs", "/configuration/ui", "/swagger-resources", "/configuration/security", "/swagger-ui.html", "/webjars/**","/swagger-resources/configuration/ui","/swagge‌​r-ui.html").permitAl‌​l()

解决办法：在启动类application中继承 SpringBootServletInitializer

并且实现以下方法

之前以为是Druid的问题，后面发现是spring注册MBean的问题，原因很简单：同一个domain里面的MBean要求name唯一。因此我们分别把不同的应用放到不同的doman问题便可以解决。在每一个SpringBoot应用的application.properties

中添加如下语句：

spring.jmx.default-domain=你随便写一个非同名的domain

---