spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档
文章目录
源码Gitub地址:https://github.com/heibaiying/spring-samples-for-all
一、Springfox 与 Swagger 简介
1.1 Springfox
Springfox 是一个开源的API Doc的框架, 它的前身是swagger-springmvc,能够完美的支持springmvc,可以将spring 接口方法自动转换为接口文档。 目前spring fox 正致力于对更多JSON API规范和标准的扩展和支持,例如:swagger,RAML和jsonapi。
1.2 Swagger
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,支持从整个API生命周期(从设计和文档到测试和部署)的开发。
swagger 是一个综合的开源项目,包含swagger-core、swagger-ui、swagger-codegen、swagger-editor等多个子项目。
- swagger-core:Swagger Core是OpenAPI规范(以前称为Swagger规范)的Java实现。
- swagger-ui:依据可视化文档,提供与API资源的可视化交互。
- swagger-codegen:开源的代码生成器,根据Swagger定义的RESTful API可以自动建立服务端和客户端的连接。
- swagger-editor:开源的api文档编辑器。
下图为swagger-ui 提供的文档可视化界面示例:

1.3 OpenApi、Swagger、Springfox的关系
Swagger Core 是 OpenApi 规范(以前称为Swagger规范)的Java 实现,而 Springfox 提供 Swagger 与 spring 的集成支持。
二、spring boot 集成 swagger 2.0
2.1 导入项目相关依赖
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.2 进行swagger个性化配置、并用@EnableSwagger2开启Swagger支持
这里需要说明的是swagger虽然是一个非常直观易用的接口调试插件,但是有可能导致接口信息泄露的危险,所以建议在开发环境和测试环境开启,在生产环境关闭。这里一共给出三种Swagger开关切换的方法:
如下面代码所示,在配置文件中配置自定义的开关参数,并在创建Docket时候,在链式调用的enable()方法中传入;
在
SwaggerConfig
配置类上添加@Profile({"dev","test"})
注解,指明在开发环境和测试环境下激活此配置类,打包或者部署时候使用spring.profiles.active指明环境即可;在配置文件中配置自定义的开关参数,并在
SwaggerConfig
配置类上添加@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
,指明配置类的生效条件注:@ConditionalOnProperty 注解说明
@ConditionalOnProperty注解能够控制某个@configuration修饰的配置类是否生效。具体操作是通过name和havingValue属性来实现,name对应application.properties(yml)中的某个属性值,如果该值为空,则返回false;如果值不为空,则将该值与havingValue指定的值进行比较,如果一样则返回true;否则返回false。如果返回值为false,则该configuration不生效;为true则生效。
/**
* @author : heibaiying
* @description : Swagger 配置类
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${swagger.enable}")
private boolean swaggerEnable;
/***
* 配置swagger
* 开发和测试环境下可以开启swagger辅助进行调试,而生产环境下可以关闭或者进行相应的权限控制,防止接口信息泄露
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(swaggerEnable)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.heibaiying.springboot.controller"))
.paths(PathSelectors.any())
.paths(doFilteringRules())
.build();
}
/***
* 接口文档的描述信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("spring boot swagger2 用例")
.description("描述")
.licenseUrl("https://mit-license.org/")
.version("1.0")
.build();
}
/**
* 可以使用正则定义url过滤规则
*/
private Predicate<String> doFilteringRules() {
return not(
regex("/ignore/*")
);
}
}
application.properties :
#swagger启用开关
swagger.enable = true
2.3 swagger注解的使用和说明
@Slf4j
@Api(value = "产品接口", description = "产品信息接口")
@RestController
public class ProductController {
/***
* 一个标准的swagger注解
*/
@ApiOperation(notes = "查询所有产品", value = "产品查询接口")
@ApiImplicitParams(
@ApiImplicitParam(name = "id", value = "产品编号", paramType = "path", defaultValue = "1")
)
@ApiResponses(value = {
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "无效的请求"),
@ApiResponse(code = 401, message = "未经过授权认证"),
@ApiResponse(code = 403, message = "已经过授权认证,但是没有该资源对应的访问权限"),
@ApiResponse(code = 404, message = "服务器找不到给定的资源,商品不存在"),
@ApiResponse(code = 500, message = "服务器错误")
})
@GetMapping(value = "/product/{id}", produces = "application/json")
public ResponseEntity<Product> getProduct(@PathVariable long id) {
Product product = new Product(id, "product" + id, new Date());
return ResponseEntity.ok(product);
}
/***
* 如果用实体类接收参数,则用实体类对应的属性名称指定参数
*/
@ApiOperation(notes = "保存产品", value = "产品保存接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "产品编号", paramType = "body", defaultValue = "1"),
@ApiImplicitParam(name = "name", value = "产品名称", paramType = "body"),
@ApiImplicitParam(name = "date", value = "产品生产日期", paramType = "body")
}
)
@PostMapping(value = "/product")
public ResponseEntity<Void> saveProduct(@RequestBody Product product) {
System.out.println(product);
return ResponseEntity.ok().build();
}
/***
* 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到
*/
@ApiOperation(notes = "该接口会被忽略", value = "产品保存接口")
@PostMapping(value = "/ignore")
public ResponseEntity<Product> ignore() {
return ResponseEntity.ok().build();
}
/**
* 不加上任何swagger相关的注解也会被扫描到 如果不希望被扫描到,需要用 @ApiIgnore 修饰
*/
@PostMapping(value = "/normal")
public ResponseEntity<Void> normal() {
return ResponseEntity.ok().build();
}
@ApiIgnore
@PostMapping(value = "/apiIgnore")
public ResponseEntity<Void> apiIgnore() {
return ResponseEntity.ok().build();
}
}
swagger 为了最大程度防止对逻辑代码的侵入,基本都是依靠注解来完成文档描述。常用注解如下:
Annotation | Attribute | Target Property | Description |
---|---|---|---|
RequestHeader | defaultValue | Parameter#defaultValue | e.g. @RequestHeader(defaultValue="${param1.defaultValue}") |
ApiModelProperty | value | ModelProperty#description | e.g. @ApiModelProperty(value="${property1.description}") |
ApiModelProperty | description | ModelProperty#description | e.g. @ApiModelProperty(notes="${property1.description}") |
ApiParam | value | Parameter#description | e.g. @ApiParam(value="${param1.description}") |
ApiImplicitParam | value | Parameter#description | e.g. @ApiImplicitParam(value="${param1.description}") |
ApiOperation | notes | Operation#notes | e.g. @ApiOperation(notes="${operation1.description}") |
ApiOperation | summary | Operation#summary | e.g. @ApiOperation(value="${operation1.summary}") |
RequestParam | defaultValue | Parameter#defaultValue | e.g. @RequestParam(defaultValue="${param1.defaultValue}") |
@Api
:Api 用在类上,说明该类的作用;@ApiOperation
:用在方法上,说明方法的作用;@ApiParam
:用在参数上,说明参数的作用;@ApiImplicitParams
:用在方法上说明方法参数的作用;@ApiImplicitParam
:用在@ApiImplicitParams注解中,描述每个具体参数;@ApiResponses
:一组@ApiResponse的配置;@ApiResponse
:请求返回的配置;@ResponseHeader
:响应头的配置;@ApiModel
:描述一个Model的信息(一般用在post创建的时候,使用@RequestBody接收参数的场景);@ApiModelProperty
:描述model的属性。@ApiIgnore
:可以用于类、方法、属性,代表该方法、类、属性不被swagger的文档所管理。
2.4 swagger-ui 可视化接口文档
接口文档访问地址:http://localhost:8080/swagger-ui.html ,文档主界面如下:

2.5 利用swagger-ui进行接口测试
点击对应接口的try it out
按钮可以进行接口测试,此时可以输入对应的参数的值,然后点击下方的Execute
按钮发送请求。


post方法可以直接修改model 对应的 json数据 ,然后点击下方的Execute
按钮发送请求。

附:源码Gitub地址:https://github.com/heibaiying/spring-samples-for-all
spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档的更多相关文章
- spring boot / cloud (三) 集成springfox-swagger2构建在线API文档
spring boot / cloud (三) 集成springfox-swagger2构建在线API文档 前言 不能同步更新API文档会有什么问题? 理想情况下,为所开发的服务编写接口文档,能提高与 ...
- Spring Boot 系列(七)Swagger2-生成RESTful接口文档
Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服 ...
- Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
- Spring Boot Swagger2自动生成接口文档
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 1.问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 2 ...
- Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
- springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
- springcloud集成swaggerui做动态接口文档
1.配置文件pom,一定要使用2.4以上的,2.4默认请求方式是json,会导致getmapping设置参数类型对对象时,swaggerui界面不能指定为其他类型,反正就是各种坑,不建议用 <d ...
- Spring Boot 集成 Swagger,生成接口文档就这么简单!
之前的文章介绍了<推荐一款接口 API 设计神器!>,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单. 你所需具备的基础 告诉你,Spring Bo ...
- Spring Boot2配置Swagger2生成API接口文档
一.Swagger2介绍 前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...
随机推荐
- ADO.net Connection对象简介
Connection对象 学习的是刘皓的文章 ADO.NET入门教程(四) 品味Connection对象 这篇文章开始水平一般起来了,主要介绍了要优雅的使用这个对象 1 用try...catch.. ...
- codeforces Round #259(div2) D解决报告
D. Little Pony and Harmony Chest time limit per test 4 seconds memory limit per test 256 megabytes i ...
- 回调函数实现类似QT中信号机制
1. 定义回调接口类: class UIcallBack { public: virtual void onAppActivated() = 0; virtual void onShowMore() ...
- otrs离线部署
OTRS5离线部署 参考地址:https://doc.otrs.org.cn/doc/manual/admin/stable/zh_CN/html/manual-installation-of-otr ...
- WPF 左键单击弹出菜单 ContextMenu
原文:WPF 左键单击弹出菜单 ContextMenu WPF中的ContextMenu在XAML中可直接做出来,但是仅限于右键弹出菜单,如果需要添加左键弹出功能,只需要在事件中添加Click事件 X ...
- fzu-1753 Another Easy Problem-高速求N!多少个月p
它计算每个C(N,M)什么号码乘以像.... #include <iostream> #include<stdio.h> #include<vector> #inc ...
- Tab切换效果的实现
<!--引用jquery和bootstrap--> <link rel="stylesheet" href="~/Content/bootstrap.m ...
- 反编译 war 包成传统项目的方法
需求 项目老大让外包做了官网,不甚满意,想自己搞搞,遂叫我反编译他们发过来的 war 包. 方法 第一步:解压 war 包其实就是 zip 压缩包,用 zip 解压. 第二步:反编译 查看 war 包 ...
- UNITY VR 视频/图片 开发心得(二)
上回说到了普通的全景图片,这回讲真正的VR. 由于这种图片分为两部分,所以我们需要两个Camera对象以及两个球体.首先新建一个Camera对象,并将其命名为RightEye(其它名字也无妨,只要你自 ...
- C# GC Finalizer IDispseable,.Net的垃圾回收机制
1.GC只能回收堆里的托管资源 2.GC 回收,"代"的概念 .net 托管资源分三代,代数越大 资源的生命周期越长. 0 代 和1代的资源比较少可以比较频率的回收, 回收2代以上 ...