快速在 SpringBoot 项目中集成 Swagger
使用方法
1. 导入依赖
<dependency>
<groupId>cn.gjing</groupId>
<artifactId>tools-starter-swagger</artifactId>
<version>1.1.0</version>
</dependency>2. 使用注解
该注解可以用在 任何类 上, 案例中将其用在启动类上
@SpringBootApplication
@EnableSwagger
public class DemoApplication {public static void main(String[] args) {SpringApplication.run(DemoApplication.class, args);
}
}3. 配置
在进行了第二步之后, 已经可以正常使用 Swagger, 各个属性都提供了默认值, 当然如果需要自己设置一些属性也可以, 所有属性如下:
- yml 格式
swagger:
contact:
email: 联系邮箱
name: 联系人昵称
url: 联系人地址
title: 标题
description: 描述
base-package: 接口所在包路径
path-type: 接口选择规则类型, 共分为: ALL(所有接口), REGEX(符合正则), ANT(符合路径)三个类型, 默认为 ALL 类型
path-pattern: 接口匹配规则, 在 path-type 类型不为 "ALL" 的情况下必须设置, 否则抛非法参数异常
exclude-pattern: 排除路径，默认使用正则表达式方式，可在 pathType 设置为其他类型(pathType 类型为 ALL 时默认走正则)
terms-of-service-url: 服务条款
license: 许可证
license-url: 许可证地址- JavaBean 方式
@Configuration
public class DemoConfig {
@Bean
public SwaggerBean swaggerBean() {return SwaggerBean.builder()
.basePackage("com.xxx.xxx")
.pathType(PathType.ALL)
.title("标题")
.termsOfServiceUrl("http://127.0.0.1")
.license("XXXX")
.licenseUrl("http://xxx.xx.xx")
.description("描述")
.build();}
} 4. 聚合文档
在实际工作中, 往往是多个服务的, 这样前端需要记住每个服务的地址, 显然太麻烦, 所以可以采用聚合文档模式, 将多个项目都聚合在一个服务里, 通常聚合在网关里, 毕竟每个服务都是走网关过得, 该模式 限于 SpringCloud 环境 , 且每个服务都在 同一个注册中心下, 参考配置如下:
- yml 格式
swagger:
resources:
enable: 是否开启聚合模式, 默认 False
register-me: 当前项目的文档是否也要加入聚合, 默认 true
# 服务列表
service-list:
- projectA: 这里可以随便定义
view: 下拉选择时展示的名字, 一般用于标识对应文档的名字
service: 服务名
- projectB:
view: 项目 b
service: demo2 - JavaBean 方式
/**
* @author Gjing
**/
@Configuration
public class GatewayConfig {
@Bean
public SwaggerResources swaggerResources() {List<Map<String, SwaggerService>> serviceList = new ArrayList<>();
Map<String, SwaggerService> service = new HashMap<>();
service.put("projectA", SwaggerService.builder().view("项目 A").service("demo").build());
serviceList.add(service);
return SwaggerResources.builder()
.enable(true)
.registerMe(true)
.serviceList(serviceList)
.build();}
}