swagger2markdown

swagger是啥？

Swagger 是一个用于把代码与文档链接起来的一个工具，我们在代码注释里写好一些东西，然后Swagger执行生成出一个网页， 这样可以方便的在网页上浏览文档，点一下测试，就可以发出一个请求。

swagger不好

近些年来，一直在使用swagger进行文档管理，从一开始感觉还是挺不错，当然很多流行语言都在使用swagger。

但是，个人感觉不太好。原因如下：

• 虽然文档可以自动生成，但是编写起来相当繁琐。繁琐也就算了，还容易报错，报错也就算了，排错更困难。只能一点一点排查。。。
• 一个地方写错了，还可能导致后面的文档都出不来。研发人员稍不注意就会把其他人的文档搞得出不来
• 在网页上的用例虽然可以用于测试，但是参数信息、是否可选等不太明确
• 一大堆接口仍在一个页面上，太多，太乱，不好查找

转战gitbook

鉴于上面所说的原因，我们研发组决定使用 gitbook 来管理文档。这是使用 markdown 文件生成页面用于展示，一个接口、一个文件、一个页面。这样子是不是清晰多了。

一个接口一个文件，各个文件互不影响。即使某一个文件写错了（md文件一般不会报错），其它文件还是可以生成页面展示。

既然决定了，那就迁移 swagger 上的接口吧，，，

然而，我稍微统计了下，我本人负责的接口有 70 多个。。。也就是要写70个markdown文件。。。

如果一个文件写1个小时，也就是70小时，我的内心是崩溃的。

但是，我仔细一想，swagger 生成json文件是有规律的，何不自己手写一个转换的脚本，一键转换生成markdown文件，岂不美哉！！！

于是乎，便有了php版本的 swagger2md

详情请往 GitHub 查看。