你还能找到比易文档更好用的接口文档工具吗？

想问下各位，你们平常开发都写 API 文档吗？我们团队协作平常都会写，大概这些情况会用到：

远程协作，这种情况接口文档肯定是必须的；
坐在一起开发，开发节奏不一致的，也需要写好接口文档给客户端，不然等他跟你对接时，你还得去翻代码，告诉他有些什么请求参数 /响应参数；
接手别人的项目，你肯定会希望有个接口文档

写接口文档的工具，我尝试过很多，我之前用过txt写、用过小幺鸡、用过apizza、用过Showdoc、看云、Gitbook、ReadTheDoc、Yapi、MinDoc、eoLinker、RAR，真的是尝试过很多个，但是他们都有一些不如意的地方。

小幺鸡：样式太丑，直接是十几年前那种table的样式，每添加一行参数都要鼠标点击一下新建，编写体验很差，预览页面真的很丑，接口调试没成功过，也用过它的markdown、富文本，体验都好差

apizza：刚开始我以为终于找到一个靠谱的了，但是！响应参数文档在哪填写！！！？另外没有 markdown，没有不限层级目录结构、子参数，最后只能抛弃。

showdoc：这个是存粹写 markdown 的，虽然可以保存模板，但是用来写 api 文档真的还是太麻烦了，跟写 txt 一样，这种体验，作为懒惰的程序猿是无法忍受的。

有些人也推荐过我那种直接代码注释生成文档的，我认为这种做法，代码里面会有特别多的注释，你要有请求参数，还要有响应参数，有些参数还是字典类型的，要是层级多了，你根本就不知道怎么表达好，代码会非常丑陋，所以一个编写体方便，体验好，预览效果优雅的文档工具才是我最需要的。

个人认为，这类开发工具，只有真正的开发者做产品经理，才能做好，才能知道他们想要什么样的效果、功能

后面自己做了一个，算是我的创业项目，易文档 https://easydoc.xyz，我保证，你用过后，再也不会想用其他的，如果你能找到一个比我们更好的，请一定告诉我们。

作为程序猿的我们，比较追求极致的输入体验，不服的，可以看下预览效果，支持在线接口调试，存为测试用例，一键生成 mock 配置

NicholasHsiang

2020-01-11 14:24:54 +08:00

支持易文档。手头一个项目（ apizza → yapi → easydoc ）：

- apizza，

好的地方：有“全局状态码”，
不好的地方太多，UI 根本不行，另外最大问题，从数据库字段生成 JSON，导入报错 JSON 格式错误，让人怀疑…果断放弃！

- yapi

好的地方：
0、开源！开源！开源！
1、导入 JSON 杠杠的，能检测 JSON 是否合法，
2、加 Mock 很方便，
3、参数“高级设置”中，加限制条件极其方便，
4、“预览”超级好，尤其是前端可以直接用生成的结构，
5、编辑参数时，加节点方便，
6、请求参数设置很方便，
7、有是否完成状态，
8、UI 非常好，限定的非常好。
9、导出超级好用，

不好的地方：
1、不能将常用字段做成模板，非常不好
2、不能复制参数字段到粘贴板，
3、接口列表中拖动调整顺序难用

- easydoc

好的地方
1、能将常用字段做成模板，并且可以编辑，太好用！太好用！太好用！
2、接口列表中拖动调整顺序好用，
3、预览模式中能复制参数字段到粘贴板
4、导入 JSON 杠杠的
不好的地方
1、Mock 难用，
2、想开选项卡，打开多了选项卡，…
3、“添加参数块”，过于灵活，Response、Request * Header、Body 不就好了？
4、没有完成与否的选项，不知道进度到哪

使用之后评论：

对比下来，easydoc “能将常用字段做成模板” 这个功能是出 API 文档时的硬需求，除了这点，完全可以选择开源的 yapi。

balabalaguguji

2020-01-13 09:53:15 +08:00

@NicholasHsiang
1.Mock 是哪里难用？我们可以一键生成 mock 哦，还支持方法、正则表达式，也有各种模板菜单给你选择，可以说编写是非常方便的。
2.不懂这个什么意思。是编辑页面多 tab ？那个是方便同时打开多个文档，方便切换、复制、参考。
3.参数块灵活是我们的一大优势，可以适用于不同需求的人，你可以定制出任何想要的模板，把自己模板保存起来，后面都可以根据模板创建 api 文档。
4.这个我们还没有，但是这个很容易解决，直接增加一个状态图标在标题上就可以了。

掌握更多易文档的技巧，你可以看下： https://easydoc.top/#/s/31322154/uOeIUcm6/FxVPkaat

xmsz

2021-02-03 15:13:33 +08:00

Api 文档一般有几类

1. Json => 自动生成文档类，例如 apiary/coding
2. 注释 => 自动生成文档（不推荐）
3. 调试主导类，例如 rap2/postman
4. 自成一派，例如 swagger
5. 文档主导类，应该就是 easyDoc 了

当然还有一些山寨货，例如 apizaza，还有一些 postman 山寨品，就是山寨还敢收费的那种

目前还在用 YApi，基本能满足 80%的需求
而比较看好的是 Rap2，有一些针对开发者更友好的功能

但是上面这两个玩意太开发者了，写文档其实很不舒服

所以看有没有更好的，楼主这个 EasyDoc 产品就是交互增强版，确实是能解决一部分需求。

但整体来说还是都没能解决的很完整。

但是这种工具吧，自己写耗时耗力，用热门的呢，要么国外慢的要死，要么国内又丑又难用

非常烦恼

然后回过头来想想到底需求是什么？

80%解决开发对开发间的问题
- 接口文档
- 接口调试
- 非必须 - Mock

能满足这些已经足够了，所以综合起来还是 YApi 更好一些，不仅开源基础功能全都有

但是要是有能解决另外 20%的产品那就更好了

而 EasyDoc 却走的是另一个方向，即不是在 YApi 上扩展解决剩余 20%的需求。而是走了另一条路，这就导致那 80%的都没做到很好

但是如果要选择二次开发，肯定还是 Rap2

还有另外一个问题，就是产品稳定性，YApi 和 Rap2 至少是有大厂支持的，其他产品都是一些韭菜拖着。
特别像这种工具，我说过解决 80%需求已经够了，所以除非你做得很好，否则根本就是瞎折腾

能看得出 EasyDoc 目的和做法是很好的，可不知道能走多远。考虑到团队因素。
除非 EasyDoc 开源，否则一般团队应该是不敢用的。