使用Swagger2Markup实现API文档的静态部署(二):Markdown和Confluence
在上一篇《使用Swagger2Markup实现API文档的静态部署(一):AsciiDoc》中,我们介绍了如何使用
Swagger2Markup
将Swagger文档转换成AsciiDoc,再将AsciiDoc转换成静态HTML。下面,本文将继续介绍Swagger2Markup可以转换的另外两个格式:Markdown和Confluence。
Swagger2Markup简介
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。
项目主页:https://github.com/Swagger2Markup/swagger2markup
如何使用
要生成Markdown和Confluence的方式非常简单,与上一篇中的方法类似,只需要修改一个参数即可。
生成Markdown和Confluence
生成方式有一下两种:
- 通过Java代码来生成:只需要修改
withMarkupLanguage
属性来指定不同的格式以及toFolder
属性为结果指定不同的输出目录。
生成markdown的代码片段:
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/markdown/generated"));
生成confluence的代码片段:
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("src/docs/confluence/generated"));
在执行了上面的设置内容之后,我们就能在当前项目的src目录下获得如下内容:
src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md
可以看到,运行之后分别在markdown和confluence目录下输出了不同格式的转换内容。
输出到单个文件
如果不想分割结果文件,也可以通过替换 toFolder(Paths.get("src/docs/asciidoc/generated")
为 toFile(Paths.get("src/docs/asciidoc/generated/all"))
,将转换结果输出到一个单一的文件中,这样可以最终生成html的也是单一的。
通过插件输出方式类似,这里不做赘述,如何引入插件可以查看上一篇文章
静态部署
下面来看看Markdown和Confluence生成结果的使用。
Markdown的部署
Markdown目前在文档编写中使用非常常见,所以可用的静态部署工具也非常多,比如:Hexo、Jekyll等都可以轻松地实现静态化部署。具体使用方法,这里按照这些工具的文档都非常详细,这里就不具体介绍了。
Confluence的部署
相信很多团队都使用Confluence作为文档管理系统,所以下面具体说说Confluence格式生成结果的使用。
第一步:在Confluence的新建页面的工具栏中选择 {}Markup
第二步:在弹出框的 Insert
选项中选择 ConfluenceWiki
,然后将生成的txt文件中的内容,黏贴在左侧的输入框中;此时,在右侧的阅览框可以看到如下图的效果了。
注意:所以 Insert
选项中也提供了Markdown格式,我们也可以用上面生成的Markdown结果来使用,但是效果并不好,所以在Confluence中使用专门的生成结果为佳。
- go语言的sql包原理与用法分析
- WordPress免插件生成完整站点地图(sitemap.xml)的php代码
- Go语言常用字符串处理方法实例汇总
- 硬盘故障时如何强制关机:Input/output error
- 举例讲解Go语言中函数的闭包使用
- 实现WordPress提交评论的时删除该页面的WP-Super-Cache缓存的方法
- php自动生成百度开放适配PC页-手机页pattern对应关系sitemap.xml
- Linux系统最大文件打开数优化,解决Too many open files报错
- 【Dev Club 分享】安卓单元测试:What, Why and How
- WordPress记住评论用户信息的js版本,直接操作cookie无视缓存
- 禁止百度转码和百度快照缓存的META声明
- 单机MySQL数据库优化推荐的编译安装参数
- Linux网络实时流量监测工具iftop的安装使用
- Golang学习--GroupCache的使用
- 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 数组属性和方法
- 第31天:面试比 KMP 还容易被问到的匹配算法!
- 原创 | 深度学习开篇,来聊聊感知机的原理
- 算法题:输入一个矩阵,按照从外向里以顺时针的顺序依次打印出每一个数字
- 使用Java和Python解题:定义栈的数据结构,请在该类型中实现一个能够得到栈中所含最小元素的min函数(时间复杂度应为O(1))。
- R语言中%||%是什么意思?
- 原创 | 你会用缓存吗?详解LRU缓存淘汰算法
- 用Java实现:输入两个整数序列,第一个序列表示栈的压入顺序,请判断第二个序列是否可能为该栈的弹出顺序。假设压入栈的所有数字均不相等。
- Hacking with iOS: SwiftUI Edition - Hot Prospects项目(一)
- 原创 | 详解command设计模式,解耦操作和回滚
- 第32天:图解大数打印,这道题如此经典!
- Mac终端配置好的环境变量在关闭终端后失效怎么办
- R中的stack和unstack函数
- 第33期:上海自来水来自海上,回文字符串验证!
- nginx location配置
- 快速学习-RocketMQ Dledger快速搭建