Spring Boot 之 Swagger
Swagger
Swagger介绍
Swagger是一套基于 OpenAPI 规范构建的开源工具- OpenAPI Specification，OAS
- 帮助设计、构建、记录以及使用 REST API
OpenAPI规范是在2015年由OpenAPI Initiative 捐赠给 Linux 基金会- 该规范创建了 RESTful 接口规范
- 通过有效映射与之关联的所有资源和操作来轻松开发和使用 API
- 主要部分
Swagger Editor- 基于浏览器的编辑器
- 可以编写 OpenAPI 规范
Swagger UI- 会将编写的 OpenAPI 规范呈现为交互式的 API 文档
- 使用浏览器来查看并且操作 Rest API
Swagger Codegen- 通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程
SpringBoot项目整合swagger需要用到两个依赖（旧版）- 用于自动生成 swagger 文档
springfox-swagger2- 用于帮助自动生成描述 API 的 json 文件
- ``springfox-swagger-ui`
- 将描述 API 的 json 文件解析出来
- 用一种更友好的方式呈现出来
- 新版只需要 SpringBoot 起步依赖
springfox-boot-starter
- 用于自动生成 swagger 文档
版本
新版本和老版本的区别主要体现在以下 4 个方面
- 依赖项的添加不同：新版本只需要添加一项
- 老版本需要添加两项
- 启动 Swagger 的注解不同：新版本使用的是
@EnableOpenApi- 老版本是
@EnableSwagger2
- 老版本是
Docket：文档摘要信息的文件类型配置不同：新版本配置的是OAS_3- 老版本是
SWAGGER_2
- 老版本是
Swagger UI访问地址不同：新版本：http://localhost:8080/swagger-ui/- 老版本访问地址是：http://localhost:8080/swagger-ui.html
使用
依赖
<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!-- springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
<!-- springboot启动依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
常用注解说明
- 只要 controller 方法返回实体类对象，在 Swagger 文档中就会有实体类数据模型
- 配置
@ApiModel、@ApiModelProperty注解以描述实体类属性、方法
- 配置
/*
用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，所以不需要配置"
*/
@Api(tags="APP用户注册Controller")
-----------------------------------------------------------
/*
用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
*/
@ApiOperation(value="用户注册",notes="必须是数字")
-----------------------------------------------------------
/*
* @ApiImplicitParams：用在请求的方法上，表示一组参数说明
* 参数是 pojo 类型，不能使用 @ApiImplicitParams 注解
* @ApiImplicitParam：在 @ApiImplicitParams 注解内部，指定一个请求参数的各个方面
* name：参数名
* value：参数的汉字说明、解释
* required：参数是否必须存在
* paramType：参数位置
* · header：获取参数 @RequestHeader
* · query： 获取参数 @RequestParam
* · path：用于 restful 接口，获取参数 @PathVariable
* · body、form（不常用）
* dataType：参数类型，默认 String；dataType="Integer"
* defaultValue：参数的默认值
*/
@ApiImplicitParams({
@ApiImplicitParam(name="mobile", value="手机号", required=true, paramType="form"),
@ApiImplicitParam(name="password", value="密码", required=true, paramType="form"),
@ApiImplicitParam(name="age", value="年龄", required=true, paramType="form",dataType="Integer")
})
-----------------------------------------------------------
/*
* @ApiResponses：用在请求的方法上，表示一组响应
* @ApiResponse：在 @ApiResponses 内部，一般用于表达一个错误的响应信息
* code：状态码，例如：400
* message：返回信息，例如"请求参数没填好"
* response：抛出异常的类
*/
@ApiOperation(value = "select1请求",notes = "多参，多类型")
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="路径没有或路径不对")
})
-----------------------------------------------------------
/*
* @ApiModel：描述实体类，一般用在 post 创建时，使用 @RequestBody 的场景，
* 请求参数无法使用 @ApiImplicitParam 注解进行描述的场景使用
* @ApiModelProperty：描述实体类属性
*/
@ApiModel(value = "Demo类",description = "测试")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Demo {
@ApiModelProperty("用户id")
private Integer id;
配置类
-
select().apis()扫描接口方式basePackage: 指定要扫描的包any: 扫描全部none：都不扫描withClassAnnotation: 扫描类上注解,传入注解反射对象
withMethodAnnotation: 扫描方法上的注解
-
.paths()：过滤的请求路径- any()：任何请求都扫描
- none()：任何请求都不扫描
- regex(final String pathRegex)：正则表达式控制
- ant()：指定要扫描的路径
@EnableOpenApi //Swagger 3 使用此注解
@Configuration
public class Swagger2Config {
// 配置 docket 以配置 Swagger 具体参数
@Bean
public Docket docket(Environment environment){
// 获取当前环境是否是生产环境：pro
boolean flag = environment.acceptsProfiles(Profiles.of("pro"));
return new Docket(DocumentationType.OAS_30) // 文档类型：3.0 版本 OAS_30
// 是否开启 Swagger: 开发环境开启，生产环境关闭
.enable(!flag)
// api 的元信息设置
.apiInfo(apiInfo())
// 配置分组：多个分组需要配置多个docket
.groupName("测试1")
// 接口调试地址
.host()
// 配置扫描接口
.select()
// 扫描方式：RequestHandlerSelectors配置
.apis(RequestHandlerSelectors. basePackage("security.controller"))
// 过滤路径
.paths(PathSelectors.ant("/user/**"))
// 构建者模式
.build()
// 支持的通讯协议集合
.protocols(newHashSet("https", "http"))
// 授权信息设置，必要的header token等认证信息
.securitySchemes(securitySchemes())
// 授权信息全局应用
.securityContexts(securityContexts());;
}
// 配置 Swagger 基本信息：apiInfo
private ApiInfo apiInfo(){
// 只能使用构造方法创建或使用默认信息：所以一项都不能少
return new ApiInfo(
"Swagger 测试使用", // 标题
"初次学习 Swagger", // 描述
"v1.0", // 版本
"urn:tos", // 组织：termsOfServiceUrl
new Contact("demo", "http:localhost:8080/", "2417500668@qq.com"), // 作者信息
"Apache 2.0", // 许可证
"http://www.apache.org/licenses/LICENSE-2.0", // 许可证链接
new ArrayList<>()); // 拓展
}
/**
* 设置授权信息
*/
private List<SecurityScheme> securitySchemes() {
ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
return Collections.singletonList(apiKey);
}
/**
* 授权信息全局应用
*/
private List<SecurityContext> securityContexts() {
return Collections.singletonList(
SecurityContext.builder()
.securityReferences(Collections.singletonList(
new SecurityReference("BASE_TOKEN",
new AuthorizationScope[]{
new AuthorizationScope("global", "")}))
).build());}
@SafeVarargs
private final <T> Set<T> newHashSet(T... ts) {
if (ts.length > 0) {
return new LinkedHashSet<>(Arrays.asList(ts));
}
return null;
}
/**
* 通用拦截器排除swagger设置，所有拦截器都会自动加 swagger 相关的资源排除信息
*/
@SuppressWarnings("unchecked")
@Override
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List<InterceptorRegistration> registrations =
(List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/webjars/**")
.excludePathPatterns("/v3/**")
.excludePathPatterns("/doc.html");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
皮肤定制
导入不同的包实现不同的皮肤定义
-
默认访问： http://localhost:8080/swagger-ui.html
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> -
bootstrap-ui： http://localhost:8080/doc.html<!-- 引入swagger-bootstrap-ui包 /doc.html--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.1</version> </dependency> -
Layui-ui：http://localhost:8080/docs.html<!-- 引入swagger-ui-layer包 /docs.html--> <dependency> <groupId>com.github.caspar-chen</groupId> <artifactId>swagger-ui-layer</artifactId> <version>1.1.3</version> </dependency> -
mg-ui：http://localhost:8080/document.html<!-- 引入swagger-ui-layer包 /document.html--> <dependency> <groupId>com.zyplayer</groupId> <artifactId>swagger-mg-ui</artifactId> <version>1.0.6</version> </dependency>
版权声明：本文为qq_66991094原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
THE END