使用 swagger 文档生成 markdown 或 asciidoc 文档

网上有许多使用 `swagger2markup-maven-plugin` 生成文档的教程, `swagger2markup-cli`这个工具的教程却相当的少, 本文将介绍如何使用官方提供的这个命令行工具进行`swagger.json`转换到`markdown`或`asciidoc`的演示.

# swagger2markup-cli 是什么?
swagger2markup-cli 提供 swagger.json 生成到 markdown 或 asciidoc 的方法, 通过配置进行文档输出格式的定制化, 与`swagger2markup-maven-plugin`相比它更简单更易于使用.

## 下载 `swagger2markup-cli`
有 2 个地址可供选择:

* [oss.jfrog.org](https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/)
 * [jcenter.bintray.com](https://oss.jfrog.org/artifactory/oss-snapshot-local/io/github/swagger2markup/swagger2markup-cli/)

> swagger2markup-cli 至少需要 **JDK8** 才能运行

选择 `swagger2markup-cli-1.3.1.jar` 或更新的版本

## 创建 `config.properties` 配置文件

```
swagger2markup.markupLanguage=MARKDOWN
swagger2markup.outputLanguage=ZH
```

配置说明:

| 属性 | 说明 | 选项 |
| ------------ | ------------ | ------------ |
| swagger2markup.markupLanguage | 目标文件类型 | MARKDOWN , ASCIIDOC(默认) |
| swagger2markup.outputLanguage | 目标文档中公共部分的语言 | ZH(中文) , EN(英文,默认)等 |

详细配置说明请看[**官方文档(3.2.5节)**][swagger]

## 生成文档
### 最终的目录结构看起来这样:

```
.\config.properties
.\swagger.json <<-原文档
.\swagger2markup-cli-1.3.1.jar
```

### 执行生成

`$java -jar swagger2markup-cli-1.3.1.jar convert -i swagger.json -f swagger -c config.properties`

`swagger2markup-cli` 参数命令, 详细请看[**官方文档(8.1.1节)**][swagger]

| 命令 | 说明 |
| ------------ | ------------ |
| -h | 查看帮助
| -d | 指定输出文件的目录 |
| -i | 指定输入文件的路径 |
| -f | 指定输出文件的路径(不带扩展名) |
| -c | 指定配置文件路径 |

### 最终生成结果:

```
.\swagger.adoc <<-目标文档
.\config.properties
.\swagger.json
.\swagger2markup-cli-1.3.1.jar
```

## 参考
 * [基于 Swagger 描述语言为 REST API 生成 Markdown 文档](http://russellluo.com/2017/10/gen-markdown-based-on-swagger-for-rest-api.html)

* [Command line interface (CLI) for Swagger2Markup](https://github.com/Swagger2Markup/swagger2markup-cli)

* [Swagger2Markup Documentation][swagger]

[swagger]: http://swagger2markup.github.io/swagger2markup/1.3.1/ "Swagger2Markup Documentation"

使用 swagger 文档生成 markdown 或 asciidoc 文档

添加新评论