做項目不是單純的寫完代碼就結(jié)束了，還有文檔，如果是接口開發(fā)，比較重要的一項就是接口文檔，現(xiàn)在比較廣泛使用的是swagger工具，在java中也提供了相應(yīng)的swagger工具。雖然swagger很好用，但是在通用性上還是弱了一些，比如說記錄到公司的文檔工具就不是很方便。
而markdown是一種相對通用的文檔格式，如果能把swagger的接口定義內(nèi)容導出成markdown文檔就好了。實際上卻是也有很多這樣的工具可以使用，不同的編程語言都有提供對應(yīng)的swagger轉(zhuǎn)markdown工具。
今天要介紹的是nodejs的swagger-markdown
使用
1 首先準備環(huán)境，安裝nodejs，配置nodejs的環(huán)境變量。
// 在命令行下查看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工具轉(zhuǎn)換為ymal內(nèi)容。
4 將swagger-ymal文件轉(zhuǎn)換為markdown內(nèi)容。使用一個ymal的測試內(nèi)容例子：
image.png
運行命令：
swagger-markdown.cmd -i .\test.ymal -o test.md
image.png
最后
有了好用的工具，寫接口文檔減少了很多煩惱...
