测试 Rails 编写的 API 能否测试和文档一起做?尝试了几个 swagger 相关 gem 都没成功

imwildcat · 2017年04月25日 · 最后由 ThxFly 回复于 2018年11月22日 · 7327 次阅读

大家都是怎么写 API 文档和测试 API 的呢?

没成功是什么原因

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

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

huacnlee 回复

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

hrz3424 回复

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

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

代码写的不是文档是注释

markdown 完毕

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

8 楼 已删除

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

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

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

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

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

需要 登录 后方可回复, 如果你还没有账号请 注册新账号