API 文档是和代码在一起比较好还是分开比较好？

2018-11-19 13:09:59 +08:00
 wuchengkai0

写一起:

优点: 好维护

缺点: 注解太多?

不写一起:

缺点: 不利于维护

理论上应该是文档先行，后写代码。大家都是如何做的？

2338 次点击
所在节点    程序员
10 条回复
noNOno
2018-11-19 13:15:02 +08:00
我个人,文档 /代码是写在一起.有项目规范,就遵从规范.
先写文档 /注解,留个空类 /空方法,然后再去实现.
CFO
2018-11-19 13:15:37 +08:00
不好维护的文档有什么用？过期的 不能用的文档还不如没有 浪费大家调接口的时间
luozic
2018-11-19 13:21:45 +08:00
swagger codegen 系列
suzic
2018-11-19 16:01:11 +08:00
用 apidoc 写在注释里。重点是写接口的一定要理解产品需求，不然写出来前端也没法用
TommyLemon
2018-11-19 16:59:58 +08:00
分开好。
要写代码（注解、注释等）不只是增加开发工作量，还得重新部署才生效，后续维护也麻烦。
TommyLemon
2018-11-19 17:00:14 +08:00
TommyLemon
2018-11-19 17:01:43 +08:00
一键自动接口回归测试，不需要写任何代码(注解、注释等全都不要)
TommyLemon
2018-11-19 17:01:53 +08:00
https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON_Auto_doc.jpg
TommyLemon
2018-11-19 17:02:34 +08:00
TommyLemon
2018-11-19 17:04:53 +08:00
自动保存请求记录、自动生成接口文档

还有
自动生成封装请求 JSON 的 Android 与 iOS 代码
一键下载自动生成的 JavaBean
多个测试账号、一键共享测试用例
等

附 开放源码、视频教程
GitHub 右上角点 ⭐Star 支持下吧 ^_^
https://github.com/TommyLemon/APIJSONAuto

这是一个专为移动设备优化的页面（即为了让你能够在 Google 搜索结果里秒开这个页面），如果你希望参与 V2EX 社区的讨论，你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://www.v2ex.com/t/509225

V2EX 是创意工作者们的社区，是一个分享自己正在做的有趣事物、交流想法，可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX