swagger转换成asciidoc，然后可以再根据asciidoc生成html或者pdf（目前只支持openapi2.0标准，这个依赖于网上的swagger2markup）
第一步：下载jar转换包（本机要下载Java JDK，配置环境变量等等）
链接: https://pan.baidu.com/s/1kEOQyPsZKXOmqgaiM2jrjA
提取码: h5xs
命令：java -jar Swagger2ToAsciidoc.jar 参数1 参数2
参数1（必填）：swagger json地址，可以是url也可以是物理路径
参数2（选填）：输出的路径，物理路径
第二步：执行完以上命令之后会生成一个名为 all.adoc 文件
可以使用AsciiDocFX工具生成对应的html，pdf（支持不好）
安装ruby
window上面直接去下载安装包：https://rubyinstaller.org/downloads/
更改国内源，参考 https://gems.ruby-china.com/
1
|
gem sources --add https://gems.ruby-china.org/ --remove https://rubygems.org/
|
安装cjk依赖
1
|
gem install asciidoctor-pdf-cjk-kai_gen_gothic
|
下载中文字体
1
|
asciidoctor-pdf-cjk-kai_gen_gothic-install
|
执行这一步超时，解决办法是手动下载字体。
字体文件都在这里：https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
CN 主题需要的是 RobotoMono 开头和 KaiGenGothicCN 开头的字体文件， 尝试用其他工具手工下载到 gem 安装目录的 data/fonts 文件夹内。
查看gem安装目录命令：
1
|
gem environment
|
在返回结果里面找到这句：
1
|
INSTALLATION DIRECTORY: E:/Ruby24-x64/lib/ruby/gems/2.4.0
|
然后在这个目录下面进入目录 gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/fonts， 将下载的字体都放进去。
使用方法
首先在build/swagger.adoc的顶部加入：
1
|
|
注意有个空格分割，目的是左边导航菜单是3级，并且自动加序号。
为了美化显示，还要将swagger.adoc中全局替换一下，将
1
|
cols=".^2,.^3,.^9,.^4,.^2"
|
替换成：
1
|
cols=".^2,.^3,.^6,.^4,.^5"
|
然后执行：
1
|
asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic -a pdf-style=KaiGenGothicCN build/swagger.adoc
|
会在swagger.adoc的同级目录生成swagger.pdf文件。
这里还有一个将OpenAPI3 转换成OpenAPI2的网址（转换不是太好）：
https://www.apimatic.io/dashboard?modal=transform
这里还有将openapi2转换成openapi3，没有反过来的功能，（估计是要慢慢放弃openapi2.0标准了）