Spring Boot 2.0---使用Swagger2构建强大的API文档
Spring Boot 2.0 ---使用Swagger2构建强大的API文档
随着前后端分离架构和微服务架构的流行,我们使用Spring Boot来构建RESTful API项目的场景越来越多。通常我们的一个RESTful API就有可能要服务于多个不同的开发人员或开发团队:IOS开发、Android开发、Web开发甚至其他的后端服务等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法就是创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
- 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
- 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示:
下面来具体介绍,在Spring Boot中使用我们自己实现的starter来整合Swagger。该整合项目的Github:https://github.com/SpringForAll/spring-boot-starter-swagger。如果您觉得它好用,欢迎Star支持我们!
准备工作
首先,我们需要一个Spring Boot实现的RESTful API工程,若您没有做过这类内容,建议先阅读上一篇教程:
Spring Boot 2.x基础教程:构建RESTful API与单元测试构建一个。或者也可以直接使用上一篇教程中的样例作为基础,即下面仓库中的chapter2-1
工程:
- Github:https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
- Gitee:https://gitee.com/didispace/SpringBoot-Learning/tree/2.x
整合Swagger2
下面,我们以上面仓库中的chapter2-1
工程进行整合改造。
第一步:添加swagger-spring-boot-starter依赖
在pom.xml
中加入依赖,具体如下:
<dependency><groupId>com.spring4all</groupId><artifactId>swagger-spring-boot-starter</artifactId><version>1.9.0.RELEASE</version> </dependency> |
第二步:应用主类中添加@EnableSwagger2Doc
注解,具体如下
@EnableSwagger2Doc @SpringBootApplication public class Chapter22Application {public static void main(String[] args) {SpringApplication.run(Chapter22Application.class, args);}} |
第三步:application.properties
中配置文档相关内容,比如
swagger.title=spring-boot-starter-swagger swagger.description=Starter for swagger 2.x swagger.version=1.4.0.RELEASE swagger.license=Apache License, Version 2.0 swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger swagger.contact.name=didi swagger.contact.url=http://blog.didispace.com swagger.contact.email=dyc87112@qq.com swagger.base-package=com.didispace swagger.base-path=/** |
各参数配置含义如下:
swagger.title
:标题swagger.description
:描述swagger.version
:版本swagger.license
:许可证swagger.licenseUrl
:许可证URLswagger.termsOfServiceUrl
:服务条款URLswagger.contact.name
:维护人swagger.contact.url
:维护人URLswagger.contact.email
:维护人emailswagger.base-package
:swagger扫描的基础包,默认:全扫描swagger.base-path
:需要处理的基础URL规则,默认:/**
更多配置说明可见官方说明:https://github.com/SpringForAll/spring-boot-starter-swagger
第四步:启动应用,访问:http://localhost:8080/swagger-ui.html
,就可以看到如下的接口文档页面:
添加文档内容
在整合完Swagger之后,在http://localhost:8080/swagger-ui.html
页面中可以看到,关于各个接口的描述还都是英文或遵循代码定义的名称产生的。这些内容对用户并不友好,所以我们需要自己增加一些说明来丰富文档内容。如下所示,我们通过@Api
,@ApiOperation
注解来给API增加说明、通过@ApiImplicitParam
、@ApiModel
、@ApiModelProperty
注解来给参数增加说明。
比如下面的例子:
@Api(tags = "用户管理") @RestController @RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下 public class UserController {// 创建线程安全的Map,模拟users信息的存储static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());@GetMapping("/")@ApiOperation(value = "获取用户列表")public List<User> getUserList() {List<User> r = new ArrayList<>(users.values());return r;}@PostMapping("/")@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")public String postUser(@RequestBody User user) {users.put(user.getId(), user);return "success";}@GetMapping("/{id}")@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")public User getUser(@PathVariable Long id) {return users.get(id);}@PutMapping("/{id}")@ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")@ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")public String putUser(@PathVariable Long id, @RequestBody User user) {User u = users.get(id);u.setName(user.getName());u.setAge(user.getAge());users.put(id, u);return "success";}@DeleteMapping("/{id}")@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")public String deleteUser(@PathVariable Long id) {users.remove(id);return "success";}}@Data @ApiModel(description="用户实体") public class User {@ApiModelProperty("用户编号")private Long id;@ApiModelProperty("用户姓名")private String name;@ApiModelProperty("用户年龄")private Integer age;} |
完成上述代码添加后,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
,就能看到下面这样带中文说明的文档了(其中标出了各个注解与文档元素的对应关系以供参考):
API文档访问与调试
在上图请求的页面中,我们看到user的Value是个输入框?是的,Swagger除了查看接口功能外,还提供了调试测试功能,我们可以点击上图中右侧的Model Schema(黄色区域:它指明了User的数据结构),此时Value中就有了user对象的模板,我们只需要稍适修改,点击下方“Try it out!”
按钮,即可完成了一次请求调用!
此时,你也可以通过几个GET请求来验证之前的POST请求是否正确。
相比为这些接口编写文档的工作,我们增加的配置内容是非常少而且精简的,对于原有代码的侵入也在忍受范围之内。因此,在构建RESTful API的同时,加入Swagger来对API文档进行管理,是个不错的选择。
代码示例
本文的完整工程可以查看下面仓库中的chapter2-2
目录:
- Github:https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
- Gitee:https://gitee.com/didispace/SpringBoot-Learning/tree/2.x
Spring Boot 2.0---使用Swagger2构建强大的API文档相关推荐
- Spring Boot 2.x基础教程:使用Swagger2构建强大的API文档
点击蓝色"程序猿DD"关注我 回复"资源"获取独家整理的学习资料! 作者 | 翟永超 来源 | didispace.com/spring-boot-learni ...
- Spring Boot 2.x基础教程:Swagger静态API文档的生成
点击蓝色"程序猿DD"关注我 回复"资源"获取独家整理的学习资料! 作者 | 翟永超 来源 | didispace.com/spring-boot-learni ...
- Spring Boot 集成 Swagger2,构建强大的 API 文档
前言 不管你是从事前端还是后端开发,相信都难免被接口文档折磨过.如果你是一个前端开发者,可能你会经常发现后端给的接口文档跟实际代码有所出入.而假设你是一个后端开发者,你可能又会觉得自己开发后端接口已经 ...
- springboot java获取版本号_深入实践Spring Boot 实战篇,大佬整理出的PDF文档
如何使用Spring Boot 本文章将会详细介绍如何使用Spring Boot.它覆盖了构建系统,自动配置和运行/部署选项等主题.我们也覆盖了一些Spring Boot最佳实践.尽管Spring B ...
- SpringBoot+Swagger2实现自动生成API文档
Swagger概述 Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计.构建.记录和使用REST API. 简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现 ...
- SpringBoot2.0 整合 Swagger2 ,构建接口管理界面
一.Swagger2简介 1.Swagger2优点 整合到Spring Boot中,构建强大RESTful API文档.省去接口文档管理工作,修改代码,自动更新,Swagger2也提供了强大的页面测试 ...
- Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- 软件架构-Spring boot集成模板引擎swagger2实现
上次说过springboot其实就是一个CI工具,如何体验出来CI的作用就是持续集成,它可以集成各种的工具,这里说说关于模板的集成引擎和Swagger. (一)Spring boot 集成模板引擎实现 ...
最新文章
- 分享一个PC端六格密码输入框写法
- opencv-Canny边缘检测(Python)
- 【ESP8266】使用ESP8266 NONOS SDK的JSON API
- 3、HTML <a>标签(超链接)
- MySQL 查看执行计划
- 三层设计模式初步分离
- ehcache rmi_EhCache复制:RMI与JGroups
- Python 中如何自动导入缺失的库?
- 以太网峰会:网络管理员已成濒危职业
- 概率论概念及机器学习中样本相似性度量之马氏距离
- 工欲善其事必先利其器之搜索引擎
- mysql 数据库管理认证_走进mysql数据库认证证书
- 计算机辅助设计技术基础教程,《计算机辅助设计技术基础》课程教案.doc
- 计算机网络组建课设心得,计算机网络课程设计心得体会
- model.load_state_dict(state_dict, strict=False)
- 解忧云SMS短信服务平台系统 短信发送系统源码 全解密随时可以二开无后门
- Jenkins系列之——第三章 Jenkins编译的第一个项目
- 计算机教学与实践,计算机教学研究与实践——2010学术年会论文集
- ffmpeg.wasm前端实现多张图片合成视频
- win7 文件夹工具栏