前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >使用Swagger2Markup实现API文档的静态部署(二):Markdown和Confluence

使用Swagger2Markup实现API文档的静态部署(二):Markdown和Confluence

作者头像
程序猿DD
发布2018-03-21 18:10:36
2.1K0
发布2018-03-21 18:10:36
举报
文章被收录于专栏:程序猿DD

在上一篇《使用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的代码片段:

代码语言:javascript
复制
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的代码片段:

代码语言:javascript
复制
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目录下获得如下内容:

代码语言:javascript
复制
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中使用专门的生成结果为佳。

本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2018-01-29,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 程序猿DD 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • Swagger2Markup简介
  • 如何使用
    • 生成Markdown和Confluence
      • 静态部署
        • Markdown的部署
        • Confluence的部署
    领券
    问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档