一款swagger转markdown工具

做项目不是单纯的写完代码就结束了，还有文档，如果是接口开发，比较重要的一项就是接口文档，现在比较广泛使用的是swagger工具，在java中也提供了相应的swagger工具。虽然swagger很好用，但是在通用性上还是弱了一些，比如说记录到公司的文档工具就不是很方便。

而markdown是一种相对通用的文档格式，如果能把swagger的接口定义内容导出成markdown文档就好了。实际上却是也有很多这样的工具可以使用，不同的编程语言都有提供对应的swagger转markdown工具。

今天要介绍的是nodejs的swagger-markdown

使用

1 首先准备环境，安装nodejs，配置nodejs的环境变量。

// 在命令行下查看node是否安装成功
node -v

2 安装swagger-markdown工具

npm install -g swagger-markdown
swagger-markdown [-h] [-v] -i [-o] [--skip-info]
Options:
  -h, --help      查看帮助信息.
  -v, --version   查看当前swagger-markdown的版本.
  -i , --input    swagger yaml文件的路径
  -o , --output   输出的markdown文件路径

3 准备好swagger-ymal的文件。如果使用的是java的swagger-ui，一般导出来的是json字符串文档，可以使用json-ymal工具转换为ymal内容。

https://www.json2yaml.com/

4 将swagger-ymal文件转换为markdown内容。使用一个ymal的测试内容例子：

image.png

运行命令：

swagger-markdown.cmd -i .\test.ymal -o test.md

image.png

最后

有了好用的工具，写接口文档减少了很多烦恼...