这是一个创建于 2104 天前的主题，其中的信息可能已经有所发展或是发生改变。
想问下各位，你们平常开发都写 API 文档吗？我们团队协作平常都会写，大概这些情况会用到：
- 远程协作，这种情况接口文档肯定是必须的；
- 坐在一起开发，开发节奏不一致的，也需要写好接口文档给客户端，不然等他跟你对接时，你还得去翻代码，告诉他有些什么请求参数 /响应参数；
- 接手别人的项目，你肯定会希望有个接口文档
写接口文档的工具，我尝试过很多，我之前用过txt写、用过小幺鸡、用过apizza、用过Showdoc、看云、Gitbook、ReadTheDoc、Yapi、MinDoc、eoLinker、RAR，真的是尝试过很多个，但是他们都有一些不如意的地方。
小幺鸡：样式太丑，直接是十几年前那种table的样式，每添加一行参数都要鼠标点击一下新建，编写体验很差，预览页面真的很丑，接口调试没成功过，也用过它的markdown、富文本，体验都好差
apizza：刚开始我以为终于找到一个靠谱的了，但是！响应参数文档在哪填写！！！？另外没有 markdown，没有不限层级目录结构、子参数，最后只能抛弃。
showdoc：这个是存粹写 markdown 的，虽然可以保存模板，但是用来写 api 文档真的还是太麻烦了，跟写 txt 一样，这种体验，作为懒惰的程序猿是无法忍受的。
有些人也推荐过我那种直接代码注释生成文档的，我认为这种做法，代码里面会有特别多的注释，你要有请求参数，还要有响应参数，有些参数还是字典类型的，要是层级多了，你根本就不知道怎么表达好，代码会非常丑陋，所以一个编写体方便，体验好，预览效果优雅的文档工具才是我最需要的。
个人认为，这类开发工具，只有真正的开发者做产品经理，才能做好，才能知道他们想要什么样的效果、功能
后面自己做了一个，算是我的创业项目，易文档 https://easydoc.xyz，我保证，你用过后，再也不会想用其他的，如果你能找到一个比我们更好的，请一定告诉我们。
作为程序猿的我们，比较追求极致的输入体验，不服的，可以看下 预览效果， 支持在线接口调试，存为测试用例，一键生成 mock 配置
 |
1
lyric 2019-03-11 00:54:59 +08:00
demo 也要注册太过分了吧。
|
 |
2
woncode 2019-03-11 00:55:25 +08:00 via Android
跟 swagger 比如何？
|
 |
3
dangyuluo 2019-03-11 02:35:24 +08:00
几个链接都打不开
坐标 37°25'3X.X"N 122°07'2X.X"W |
 |
4
wzw 2019-03-11 07:49:10 +08:00 via iPhone
可以测试接口吗
|
 |
5
balabalaguguji OP @lyric #1 看 demo 不用注册的
|
|
6
balabalaguguji OP @woncode #2 swagger 是写注释那种的，参数多了会很乱，污染代码，也无法写调用示例、markdown。预览效果也完全没有我们的好看
|
|
7
balabalaguguji OP @wzw #4 接口测试可以，而且测完还可以保存你的结果（存为测试用例），更方便他人明白接口调用方法，也方便自己保存一些常用的调用结果，比如接口需要登陆后返回的 token，你可以把登陆结果存为测试用例，下次用时直接查看测试用例就知道 token 了
|
 |
8
andychen1 2019-03-11 08:47:00 +08:00 via iPhone
apizza 大法好
|
 |
9
secsilm 2019-03-11 08:48:25 +08:00 via Android
一直在找一个可以直接自动生成 api 文档的工具
|
 |
10
yogogo 2019-03-11 08:48:43 +08:00
apiDoc
|
|
11
balabalaguguji OP @andychen1 #8 你可以试下我们的，我有信心你不会再用其他的
|
|
12
balabalaguguji OP @yogogo #10 这个好像是写注释的，不是很适合我，体验也远没我们的好
|
 |
14
Spoter 2019-03-11 09:01:21 +08:00
gitbook 不好用吗。。。
|
|
15
balabalaguguji OP @Spoter #14 写 api 文档不适合
|
 |
16
feehey 2019-03-11 10:01:54 +08:00
Yapi 真香
|
|
17
balabalaguguji OP @x86 #13 google 也在用 xyz
|
 |
18
nzzzg 2019-03-11 12:14:05 +08:00
页面挂了？ 进去是个空白页面
|
|
20
balabalaguguji OP @nzzzg 什么浏览器，我们不支持 IE
|
 |
21
jigi330 2019-03-11 12:41:43 +08:00 via Android
挺好看的呀，回头试试
|
|
22
balabalaguguji OP |
 |
23
ericv 2019-03-11 12:44:55 +08:00
postman 足够了。。。
|
|
24
balabalaguguji OP @ericv postman 主要只做接口测试这块的，文档功能很差，我们是文档+测试+测试用例+mock 一体，写完文档可以直接测试，测试完可以直接保存作为 demo，服务端还没开发好接口还可以一键生成 mock 配置，不影响客户端开发
|
|
25
wzw 2019-03-11 12:48:13 +08:00
@balabalaguguji #22 那自动化测试 方面呢
|
 |
26
w516322644 2019-03-11 12:48:39 +08:00
YAPI?
|
|
27
balabalaguguji OP @wzw #25 这个还在排期开发中，后面会提供
|
 |
28
yixiang 2019-03-11 12:51:49 +08:00
竞品太多，还都免费，不知能盈利否。
|
|
29
balabalaguguji OP @yixiang #28 当初也是为了自己方便开发的，后面越做越好，就成了产品，说实话，我们现在做的体验是市面第一的，不怕竞争。
|
 |
30
laogui 2019-03-11 13:04:25 +08:00 via Android
xyz 域名感觉是那种过几天就打不开的网站
|
 |
31
jabin88 2019-03-11 14:08:09 +08:00
没感觉比其他竞品好，还收费
|
 |
32
chennqqi 2019-03-11 16:15:09 +08:00
https://app.swaggerhub.com 个人用户免费，github 登录，可以公开可以私有，没发现比这个更好的；
楼主可以对照一下 |
|
34
balabalaguguji OP @chennqqi #32 这个我们对比过了，远没我们的好，我们的个人用户也是免费
|
 |
35
lqzhgood 2019-03-11 16:28:04 +08:00
刚好做完一个个人项目~ 试用一下。
lz 加油哦 |
|
36
lqzhgood 2019-03-11 16:35:20 +08:00
接口描述 我感觉这样排列比较好~
是否必须 参数类型 参数名 描述 前面 2 个 宽度基本是一定的。 描述也许会很长。 这样比较对仗工整。 是否必须 使用 ( 是 /否 ) 或者 多选框的勾选 来显示。 比较干净。 |
|
37
chennqqi 2019-03-11 16:41:15 +08:00
@balabalaguguji are you sure?
听你说的比较好用，我专门注册登录试了一下你的产品。 给你们的产品提个建议: 接口文档的有个规范叫 openapi，目前是 3.x 版本，按照这个规范可以导出到多种开发语言 可以自动 mock 目前这块儿同类的有 RAML，blueprint 你们都可以对照一些。 根据我的经验在大厂环境下不支持 swagger/openapi 格式直接可以 pass 了 淘宝有这么一款开源产品 RAP 和 rap2 你可以了解一下 可以把同类产品和你的产品特性对比发出来看看哈。 希望你们越做越好，能把 swaggerhub 替代了，真不想再用 swaggerhub 了，国内访问奇慢无比，但就是没找到更好的。 |
|
38
balabalaguguji OP @chennqqi #37 你说的规范，那都是数据的格式了，写个脚本转换下就可以了。但是对于用户来说，我们更需要关注编写是否便捷，是否快速，预览时是否够清晰明了。你说的那个是直接写注释的，那种方式很麻烦，代码也会被严重污染，特别是参数多、有多层级参数返回时，一大片都是注释，这种跟写 txt 的感觉是一样的，建议你体验下我们的编写方式，完全不是一个级别的。
|
|
39
chennqqi 2019-03-12 13:52:41 +08:00
话不投机，就此打住
|
 |
40
LeonKennedy 2019-03-12 23:30:13 +08:00
歪个题，网站前端用什么做的，服务条款那个页面好漂亮啊，正好有需要拿来用了
|
|
41
balabalaguguji OP @LeonKennedy #用 vuejs+elementui
|
 |
42
aliangddd 2019-05-16 19:41:05 +08:00 via iPhone
看着不错
|
 |
43
dNib9U2o8x 2019-05-29 23:18:58 +08:00
免费版限制成员和文档数量没问题，但是导入导出都必须付费，这个是不是有点过分了?
|
|
44
balabalaguguji OP @dNib9U2o8x #43 你得看看别人付出了多少，你又贡献了什么，为什么导入导出付费就过分了？
|
|
45
dNib9U2o8x 2019-05-30 19:00:04 +08:00
@balabalaguguji #44 我作为一个用户需要贡献什么？没有试用上来就充值？本来是要测试下效果，打算导入 swagger 或 postman 看看兼容情况，发现导入要收费，也就没有继续尝试的欲望了
|
|
46
balabalaguguji OP @dNib9U2o8x 我们的免费版本实际上是很足够用的，免费额度很大；导入 swagger 和 postman 还没支持，如果支持了，这种导入肯定会是免费的。
|
 |
47
playscforever 2019-07-18 22:56:02 +08:00
支持~
|
 |
48
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。 |
|
49
balabalaguguji OP @NicholasHsiang
1.Mock 是哪里难用？我们可以一键生成 mock 哦，还支持方法、正则表达式，也有各种模板菜单给你选择，可以说编写是非常方便的。 2.不懂这个什么意思。是编辑页面多 tab ？那个是方便同时打开多个文档，方便切换、复制、参考。 3.参数块灵活是我们的一大优势，可以适用于不同需求的人，你可以定制出任何想要的模板，把自己模板保存起来，后面都可以根据模板创建 api 文档。 4.这个我们还没有，但是这个很容易解决，直接增加一个状态图标在标题上就可以了。 掌握更多易文档的技巧，你可以看下： https://easydoc.top/#/s/31322154/uOeIUcm6/FxVPkaat |
 |
50
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 开源，否则一般团队应该是不敢用的。 |
 |
51
anankun 2021-03-25 11:40:56 +08:00
私有化部署的刚需，没有这个功能的很难能纳入考虑。
|
|
52
balabalaguguji OP @anankun #51 私有部署是收费的
|
Select Language