做项目不是单纯的写完代码就结束了，还有文档，如果是接口开发，比较重要的一项就是接口文档，现在比较广泛使用的是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内容。
4 将swagger-ymal文件转换为markdown内容。使用一个ymal的测试内容例子：
image.png
运行命令：
swagger-markdown.cmd -i .\test.ymal -o test.md
image.png
最后
有了好用的工具，写接口文档减少了很多烦恼...
