没成功是什么原因

手工用 Markdown 写 API 文档，那些工具都最终只能玩玩而已。

安安心心用 MiniTest 或 RSpec 编写逻辑测试

不过我们公司要求把文档写在接口上面的，好坑爹啊，看了就不舒服

代码的地方当然应该要写文档，但应该有额外一份更详细的手工编写的 API 文档

当然，我也希望能有好的工具能像 RDoc/Yardoc 那样自动生成，但目前没找到好的。

代码写的不是文档是注释

markdown 完毕

还可以用 apipie 的 比 markdown 集成度高，比 swagger 轻量很多

我们最开始使用 github 的 wiki 来写 markdown
但是经常忘记再修改完毕代码之后更新对应的 markdown 最终导致文档失效。

我在想，能不能用 vcr 记录下集成测试的 json 值 一旦有变化，自动发钉钉什么的要求开发补完，否则项目状态就是红的，之后前端只使用状态为绿的的 api

Rails 没有找到类似 grape-swagger这样直接能用的。只发现一个swagger-docs 勉强能用，不支持最新的 swagger ui，某一个 2.2.x 的 tag 可以兼容，需要手动执行生成 json 文件。swagger ui 要自动加载也需要自己改对应 js，坑挺多，不过改改还是能满足使用，现在的项目已经集成。

可以试试 http://apidocjs.com/

slate

可以一起做，运行自动化接口测试时，可以顺手打下日志，日志既可以是 API 日志，也可以是 postman 日志
我目前用在项目里，没有封装成 gem，文档格式可以自己定义，花两个小时就可以搭起来了。
通过测试代码，自动生成 API 文档
通过测试代码，自动生成 postman 文件

目前是放在 Redmine 的 Wiki 里，把参数校验当做参数说明文档