使用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中使用专门的生成结果为佳。
推荐阅读
使用Swagger2Markup实现API文档的静态部署(一):AsciiDoc
消息驱动的微服务(核心概念)【Dalston版】
请不要在“微服务”的狂热中迷失自我!
Netflix 的上线工具 Spinnaker
长按指纹
一键关注
点击 “阅读原文” 看看本号其他精彩内容
使用Swagger2Markup实现API文档的静态部署(二):Markdown和Confluence相关推荐
- 使用Swagger2Markup实现API文档的静态部署(一):AsciiDoc
在阅读本文之前,您先需要了解Swagger的使用,如果您还不知道它是用来干嘛的,请先阅读<Spring Boot中使用Swagger2构建强大的RESTful API文档>一文. 前言 在 ...
- Golang 见证 godoc 的强大(生成API文档,打印文档)
Golang 见证 godoc 的强大(生成API文档,打印文档) 文章目录 Golang 见证 godoc 的强大(生成API文档,打印文档) 一.godoc 介绍 二.godoc 安装 ① 系统环 ...
- Spring Boot 2.x基础教程:Swagger静态API文档的生成
点击蓝色"程序猿DD"关注我 回复"资源"获取独家整理的学习资料! 作者 | 翟永超 来源 | didispace.com/spring-boot-learni ...
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api(二十)
一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring r ...
- java文档注释生产api没有注释_一个神奇的没有springboot注释的api文档生成器---JApiDocs...
入门 支持JDK:1.8+ 快速开始 第一步:添加依赖 maven: io.github.yedaxia japidocs 1.4.3 gradle: compile 'io.github.yedax ...
- java api文档_细说API – 文档和前后端协作
在上一篇文章--<细说API – 重新认识RESTful>中介绍了如何理解和设计RESTful风格的API,现在我们来聊聊如何有效的呈现API文档,以及前后端协作的方式. 我经历过一些没有 ...
- 如何使 WebAPI 自动生成漂亮又实用在线API文档
1.前言 1.1 SwaggerUI SwaggerUI 是一个简单的Restful API 测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON 配置显示API. 项目本身仅仅也只依赖 ...
- swagger api文档_带有Swagger的Spring Rest API –创建文档
swagger api文档 使REST API易于使用的真正关键是好的文档. 但是,即使您的文档做得很好,您也需要设置公司流程的权利以正确,及时地发布它. 确保利益相关者按时收到是一回事,但是您也要负 ...
- swagger api文档_带有Swagger的Spring Rest API –公开文档
swagger api文档 创建API文档后,将其提供给涉众很重要. 在理想情况下,此发布的文档将足够灵活以解决任何最后的更改,并且易于分发(就成本以及完成此操作所需的时间而言). 为了使之成为可能, ...
最新文章
- JDK1.5官方下载_JDK5官方下载_JDK1.5API(chm)下载_JDK5APICHM中文参考下载_JDK1.5下载_JDK5下载...
- cmake (0)简介
- MySQL带BETWEEN AND关键字的查询
- Boost:字符串查找子串测试实例
- android 应用在启动后进行全局的的初始化操作
- 搭建python_Crawlab准备之python+scrapy环境搭建
- 主板和cpu搭配表_主板和CPU如何搭配?主板和处理器搭配方法
- 机器学习分类_机器学习之简单分类模型
- 奢华还是土嗨?8848新品钛金手机将于3月29日开启预售
- Linux(3)--防火墙
- 修复linux bash破壳漏洞,Linux系统下如何检测并修复bash中的破壳漏洞​​
- 查询所有的oracle表、表空间、数据库连接等信息
- 奇异值分解(SVD)和最小二乘解在解齐次线性超定方程中的应用
- 监控提示服务器状态变更,服务器故障排除与状态监控
- 捷联惯导系统模型及仿真
- 如何利用PS做文字拼接海报
- 统计相关系数(1)——Pearson(皮尔逊)相关系数及MATLAB实现
- php计算器按钮功能,PHP实现的简单在线计算器功能示例
- 判断三维空间两线段是否相交(附代码)
- vue安装vue-awesome-swiper@3实现图片列表缩略图双向控制效果
热门文章
- linux shell 执行 几种方式区别 bash source .
- linux c 解析生成json(jansson安装和使用)
- ring0下的 fs:[124]
- QEMU虚拟网卡设备的创建流程
- java字符串反转的方法,Java实现字符串反转的几种方法
- 数据结构 - 反转单链表(C++)
- XSLT - 利用template实现for循环
- 网络工程制图论文计算机,学习系统与工程制图论文
- computed vue 不 触发_vuejs render何时执行?以及使用vue.$refs遇到的坑。
- php点击按钮做查找,点击按钮后运行PHP功能?