Spring Boot 之 Swagger

文章目录

Swagger
- 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

版本

新版本和老版本的区别主要体现在以下 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 具体参数@Beanpublic Docket docket(Environment environment){// 获取当前环境是否是生产环境：proboolean 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 基本信息：apiInfoprivate ApiInfo apiInfo(){// 只能使用构造方法创建或使用默认信息：所以一项都不能少return new ApiInfo("Swagger 测试使用",                                                    // 标题"初次学习 Swagger",                                                  // 描述"v1.0",                                                             // 版本"urn:tos",                                                           // 组织：termsOfServiceUrlnew 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());}@SafeVarargsprivate final <T> Set<T> newHashSet(T... ts) {if (ts.length > 0) {return new LinkedHashSet<>(Arrays.asList(ts));}return null;}/*** 通用拦截器排除swagger设置，所有拦截器都会自动加 swagger 相关的资源排除信息*/@SuppressWarnings("unchecked")@Overridepublic 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>

Spring Boot 之 Swagger相关推荐

Spring Boot集成Swagger导入YApi@无界编程
接口APi开发现状现在开发接口都要在类似YApi上写文档,这样方便不同的团队之间协作,同步更新接口,提高效率. 但是如果接口很多,你一个个手工在YApi去录入无疑效率很低. 如果是使用Spring ...
spring boot集成swagger，自定义注解，拦截器，xss过滤，异步调用，定时任务案例...
本文介绍spring boot集成swagger,自定义注解,拦截器,xss过滤,异步调用,定时任务案例集成swagger--对于做前后端分离的项目,后端只需要提供接口访问,swagger提供了接口 ...
Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
Spring Boot 整合 Swagger
一.为什么要用 Swagger 现在的开发模式,一般都是前后端分离的,开发接口文档就显得尤为重要,前端人员需要按照后端的功能文档调用对应的接口.在没有使用 API 文档之前,很多公司都是在纸或者 Ma ...
Spring Boot和Swagger UI
我已经一年没有从头开始开发Spring Web应用程序了,如果我不参加QA自动化工程师的培训,那么这段时间甚至会更长. 由于这个原因,我开发了一个示例REST应用程序. 除了Swagger,一切对我来 ...
Spring Boot集成Swagger
Spring Boot集成Swagger @(Swagger)[swagger, springfox, springboot] Spring Boot集成Swagger 前言基本概述案例引入依赖 ...
Spring boot :使用 Swagger 2 构建 RESTful APIs
1.美图 2.什么是 Swagger Swagger 是一系列列 RESTful API 的⼯具,通过 Swagger 可以获得项⽬的一种交互式⽂档,客户端 SDK 的⾃动⽣生成等功能. Swagge ...
Spring Boot 整合Swagger实现API管理
Spring Boot 整合Swagger实现API管理 1 Swagger介绍根据官网的介绍: https://swagger.io Swagger 是一款RESTFUL接口的.基于YAML.JS ...
spring boot 使用swagger
在pom.xml中添加maven依赖 <dependency><groupId>io.springfox</groupId><artifactId>sp ...
Spring Boot 禁用 Swagger 的三种方式
一.序言在生产环境下,我们需要关闭swagger配置,避免暴露接口的这种危险行为. 二.方法: 禁用方法1: 使用注解 @Value() 推荐使用 package com.dc.config;imp ...