Swagger2在DBA Service中生成RESTful API的实践
目的与背景:
目的:对外暴露DBA Service必要的RESTful API,形成规整的API文档
背景:DBA Service后端采用Spring-boot,属于Spring家族,故生成API的工具采用基于Swagger2实现的SpringFox-Swagger2
一、API在线生成配置
1、通过Maven引入springfox-swagger2
和 springfox-swagger-ui两个依赖,如下:
<dependency> |
---|
2、创建Swagger2配置类
(1)在和WatchmanApplication启动类平行的路经下创建Swagger.java (类名自定)
(2)类内容如下:
@Configuration |
---|
其中,@Configuration@EnableSwagger2两个注解是装配和启用Swagger2的标志;
apiInfo()函数定义配置信息;createRestApi()返回API。
3、在Controller处配置要对外暴露的API注解
注解说明(具体百度,同时参考代码中的使用):
实体类:
@ApiModel和
@ApiModelProperty用于在通过对象接收参数时在API文档中显示字段的说明
控制类:@Api、@ApiOperation 、
@ApiImplicitParams&
@ApiImplicitParam 、@ApiResponses&@ApiResponse 、@ApiIgnore
4、WebUI形式访问
此时将项目正常启动,通过 http://localhost:8888/swagger-ui.html 来访问,localhost换成DBA Service所在的主机IP
二、生成离线html和pdf的静态API文档
需要借助Swagger2Markup开源工具生成AsciiDoc,AsciiDoc再被解析执行生成静态html和pdf。
5、Maven引入相关依赖,分两部分
(1)引入Swagger2Markup相关的依赖
... <dependency> <repositories> |
---|
(2)引入解析AsciiDoc来生成HTML和PDF的插件依赖
下面是结合各方自己调配的,生成HTML和PDF的通过<execution>标签使其独立各自执行一次,最终分别生成静态HTML和PDF文档。(其中一定要注意路经配置)
<plugin> |
---|
6、编写一个单元测试(我的单元测试类命名为Swagger2Test),目的是用来生成执行生成文档的代码,我的定义如下:
@RunWith(SpringRunner.class) |
---|
本项目需求是生成一个完整的html和pdf,使用的是toFile()函数。其中必须要指定两项内容(绿色部分),前者是API的Json访问URL路经;后者是生成的执行生成文档的代码所保存到的路经。
备注:这里遇到一个坑,即Swagger2Markup依赖的common-beanutils和其他依赖这个包产生了冲突,我显示的把common-beanutils1.9.4放到了前边高优先级的位置,也就是之后不管哪个依赖的commons-beanutils都是1.9.4
7、运行单元测试(Swagger2Test)
注意:运行前一定要关闭IDE里启动的DBA Service,否则启动单元测试就拿不到Application Context,一定是冲突了。
正确执行完单元测试,可以看到/src/main/resources/docs/asciidoc/generated路经(这个路经就是单元测试中配置的那个路经)下多出了一个all.adoc文件。
这个all.adoc文件就是用来执行生成html和pdf的原始代码。我的all.adoc在IDEA中如下图:
8、执行如下两条maven命令即可生成HTML和PDF静态文档,我的生成后在IDEA中如下图:
|
---|
Swagger2在DBA Service中生成RESTful API的实践的更多相关文章
- 使用Swagger2构建SpringMVC项目中的Restful API文档
使用Swagger自动生成API文档,不仅增加了项目的可维护性,还提高了API的透明度更利于快速测试等工作,便于更快地发现和解决问题. 本篇文章只记录整合过程,关于Security Configura ...
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- 基于querybuilder的可根据现有数据表自动生成Restful API的dotnet中间件
AutoApi 基于SqlKata Query Builder的可根据数据表自动生成Restful API的dotnet中间件 项目地址 Github Gitee 支持的数据库 MySql AutoA ...
- 在C#中使用RESTful API的几种好方法
什么是Restful API REST 即Representational State Transfer的缩写.直接翻译的意思是"表现层状态转化". 它是一种互联网应用程序的API ...
- 我所理解的Restful API最佳实践
一直在公司负责API数据接口的开发,期间也遇到了不小的坑,本篇博客算是做一个小小的记录. 1. 不要纠结于无意义的规范 在开始本文之前,我想先说这么一句:RESTful 真的很好,但它只是一种软 ...
- 我所认为的RESTful API最佳实践
我所认为的RESTful API最佳实践 不要纠结于无意义的规范 在开始本文之前,我想先说这么一句:RESTful 真的很好,但它只是一种软件架构风格,过度纠结如何遵守规范只是徒增烦恼,也违背了使用它 ...
- Spring Boot中使用Swagger2生成RESTful API文档(转)
效果如下图所示: 添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!-- https://mvnrepository.com/artifact/io.springfox ...
随机推荐
- 使用powerdesigner进行数据库设计
powerdesigner安装破解文件:链接:https://pan.baidu.com/s/1oKAdUqTKElQ9d86FV-SDTQ 密码:l4y5 基本操作参考:1.PowerDesigne ...
- java内存区域----运行时数据区
Java虚拟机的内存区域也叫做java运行时数据区,共分为五个部分:程序计数器,方法区,本地方法栈,虚拟机栈和堆.方法区和堆是线程之间所共有的,程序计数器,本地方法栈,虚拟机栈是线程私有的.其中虚拟机 ...
- pip install mysqlclient报错(OSError: mysql_config not found)
报错截图 一般情况是系统没有安装libmysqld-dev 执行 sudo apt install libmysqld-dev完成安装后再 pip install mysqlclient就可以了(系统 ...
- JUC常用同步工具类——CountDownLatch,CyclicBarrier,Semaphore
在 JUC 下包含了一些常用的同步工具类,今天就来详细介绍一下,CountDownLatch,CyclicBarrier,Semaphore 的使用方法以及它们之间的区别. 一.CountDownLa ...
- 用vue + leancloud开发一个免费的博客
项目地址 https://github.com/Fee-ing/Fe... 在线预览 在线预览地址: 搭建免费博客
- direction和writing-mode的介绍
direction介绍 属性值和兼容都很好 CSSdirection属性简单好记,属性值少,兼容性好,关键时候省心省力,是时候给大家宣传宣传,不要埋没了人家的特殊技能. Chrome Safari F ...
- vue之initComputed模块源码说明
要想理解原理就得看源码,最近网上也找了好多vue初始化方法(8个init恶魔...) 因为也是循序渐进的理解,对initComputed计算属性的初始化有几处看得不是很明白,网上也都是含糊其辞的(要想 ...
- css的相对定位与绝对定位
css相对定位:是相对于它本身最近的父级定位 css绝对定位:是对于它本身最接近的参照物来定位,如果没有就对于body来定位
- JZOJ 5329. 【NOIP2017提高A组模拟8.22】时间机器
5329. [NOIP2017提高A组模拟8.22]时间机器 (File IO): input:machine.in output:machine.out Time Limits: 2000 ms M ...
- 峰哥说技术:04-Spring Boot基本配置
Spring Boot深度课程系列 峰哥说技术—2020庚子年重磅推出.战胜病毒.我们在行动 04 Spring Boot基本配置 1)容器的相关配置 在Spring Boot中可以内置Tomcat. ...