使用Swagger2Markup实现API文档的静态部署(一):AsciiDoc
在阅读本文之前,您先需要了解Swagger的使用,如果您还不知道它是用来干嘛的,请先阅读《Spring Boot中使用Swagger2构建强大的RESTful API文档》一文。
前言
在学会了如何使用Swagger之后,我们已经能够轻松地为Spring MVC的Web项目自动构建出API文档了。但是,如前文方式构建的文档必须通过在项目中整合 swagger-ui
、或使用单独部署的 swagger-ui
和 /v2/api-docs
返回的配置信息才能展现出您所构建的API文档。本文将在使用Swagger的基础上,再介绍一种生成静态API文档的方法,以便于构建更轻量部署和使用的API文档。
Swagger2Markup简介
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。
项目主页:https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前,我们先需要准备一个使用了Swagger的Web项目,可以是直接使用Swagger2的项目,也可以是使用了spring-boot-starter-swagger的项目,比如我仓库中的:https://github.com/dyc87112/swagger-starter-demo ,下面就来看看如何使用Swagger2Markup来创建AsciiDoc。
生成AsciiDoc
生成AsciiDoc的方式有两种:
- 通过Java代码来生成
第一步:编辑 pom.xml
增加需要使用的相关依赖和仓库
<dependencies>
...
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
</dependencies>
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
第二步:编写一个单元测试用例来生成执行生成文档的代码
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
@Test
public void generateAsciiDocs() throws Exception {
// 输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/asciidoc/generated"));
}
}
以上代码内容很简单,大致说明几个关键内容:
-
MarkupLanguage.ASCIIDOC
:指定了要输出的最终格式。除了ASCIIDOC之外,还有MARKDOWN和CONFLUENCE_MARKUP -
from(newURL("http://localhost:8080/v2/api-docs")
:指定了生成静态部署文档的源头配置,可以是这样的URL形式,也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目,我们通过使用访问本地Swagger接口的方式,如果是从外部获取的Swagger文档配置文件,就可以通过字符串或读文件的方式 -
toFolder(Paths.get("src/docs/asciidoc/generated")
:指定最终生成文件的具体目录位置
在执行了上面的测试用例之后,我们就能在当前项目的src目录下获得如下内容:
src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc
可以看到,这种方式在运行之后就生成出了4个不同的静态文件。
输出到单个文件
如果不想分割结果文件,也可以通过替换 toFolder(Paths.get("src/docs/asciidoc/generated")
为 toFile(Paths.get("src/docs/asciidoc/generated/all"))
,将转换结果输出到一个单一的文件中,这样可以最终生成html的也是单一的。
- 通过Maven插件来生成
除了通过上面编写Java代码来生成的方式之外,swagger2markup还提供了对应的Maven插件来使用。对于上面的生成方式,完全可以通过在 pom.xml
中增加如下插件来完成静态内容的生成。
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
<swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
<outputDir>src/docs/asciidoc/generated</outputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
</config>
</configuration>
</plugin>
生成HTML
好了,完成了从Swagger文档配置文件到AsciiDoc的源文件转换之后,就是如何将AsciiDoc转换成可部署的HTML内容了。这里继续在上面的工程基础上,引入一个Maven插件来完成。
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<outputDirectory>src/docs/asciidoc/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<toc>left</toc>
</attributes>
</configuration>
</plugin>
通过上面的配置,执行该插件的asciidoctor:process-asciidoc命令之后,就能在 src/docs/asciidoc/html
目录下生成最终可用的静态部署HTML了。在完成生成之后,可以直接通过浏览器来看查看,你就能看到类似下图的静态部署结果:
是不是感觉似曾相识呢?是的,Spring Cloud的E版之前的文档也是这样的!!!
- 碎片化 | 第四阶段-45-session为空问题解决-视频
- 以后有机会写框架用得着的
- 合并两个不相关的Git仓库
- 用 Tensorflow 建立 CNN
- 碎片化 | 第四阶段-36-struts-spring结合jdbc实现删除功能-视频
- 跨域访问支持(Spring Boot、Nginx、浏览器)
- 自己动手写个聊天机器人吧
- 碎片化 | 第四阶段-37-sturts2-登录功能实现-视频
- Spring Cloud Edgware新特性之六:Artifact ID变更
- 用 RNN 训练语言模型生成文本
- 碎片化 | 第四阶段-38-Struts2登录session对象封装-视频
- LeetCode实战:子问题分析
- 5分钟构建一个自己的无人驾驶车
- 碎片化 | 第四阶段-39-Struts2中session对象梳理-视频
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- @Component和@Bean以及@Autowired、@Resource
- mybatis generator and 和or条件
- 『.Net反射』ILGenerator.Emit 动态MSIL 编程
- Spring通过XML配置文件以及通过注解形式来AOP 来实现前置,后置,环绕,异常通知
- 切面编程(环绕通知与前后置通知区别)
- Spring在代码中获取bean的几种方式
- Spring 一个接口多个实现类怎么注入
- ASP.NET MVC Controller的激活
- js 逗号表达式
- spring动态调用方法
- Spring AOP动态代理原理与实现方式
- 基于注解多数据源解决方案
- Java并发编程:CountDownLatch、CyclicBarrier和Semaphore
- 你需要实现一个高效的缓存,它允许多个用户读,但只允许一个用户写,以此来保持它的完整性,你会怎样去实现它?
- java阻塞队列得实现