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 classSwagger2 {
// @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 newDocket(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 classSwagger2 {
@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 newDocket(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数据实现文档聚合管理
