V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
balabalaguguji
V2EX  ›  分享创造

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

  •  
  •   balabalaguguji · 2019-03-10 23:33:44 +08:00 · 9257 次点击
    这是一个创建于 2089 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

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

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

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

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

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

    52 条回复    2021-03-25 13:34:00 +08:00
    lyric
        1
    lyric  
       2019-03-11 00:54:59 +08:00
    demo 也要注册太过分了吧。
    woncode
        2
    woncode  
       2019-03-11 00:55:25 +08:00 via Android
    跟 swagger 比如何?
    dangyuluo
        3
    dangyuluo  
       2019-03-11 02:35:24 +08:00
    几个链接都打不开
    坐标 37°25'3X.X"N 122°07'2X.X"W
    wzw
        4
    wzw  
       2019-03-11 07:49:10 +08:00 via iPhone
    可以测试接口吗
    balabalaguguji
        5
    balabalaguguji  
    OP
       2019-03-11 08:17:31 +08:00
    @lyric #1 看 demo 不用注册的
    balabalaguguji
        6
    balabalaguguji  
    OP
       2019-03-11 08:25:00 +08:00
    @woncode #2 swagger 是写注释那种的,参数多了会很乱,污染代码,也无法写调用示例、markdown。预览效果也完全没有我们的好看
    balabalaguguji
        7
    balabalaguguji  
    OP
       2019-03-11 08:29:57 +08:00
    @wzw #4 接口测试可以,而且测完还可以保存你的结果(存为测试用例),更方便他人明白接口调用方法,也方便自己保存一些常用的调用结果,比如接口需要登陆后返回的 token,你可以把登陆结果存为测试用例,下次用时直接查看测试用例就知道 token 了
    andychen1
        8
    andychen1  
       2019-03-11 08:47:00 +08:00 via iPhone
    apizza 大法好
    secsilm
        9
    secsilm  
       2019-03-11 08:48:25 +08:00 via Android
    一直在找一个可以直接自动生成 api 文档的工具
    yogogo
        10
    yogogo  
       2019-03-11 08:48:43 +08:00
    apiDoc
    balabalaguguji
        11
    balabalaguguji  
    OP
       2019-03-11 08:49:42 +08:00
    @andychen1 #8 你可以试下我们的,我有信心你不会再用其他的
    balabalaguguji
        12
    balabalaguguji  
    OP
       2019-03-11 08:51:39 +08:00
    @yogogo #10 这个好像是写注释的,不是很适合我,体验也远没我们的好
    x86
        13
    x86  
       2019-03-11 08:59:21 +08:00
    Spoter
        14
    Spoter  
       2019-03-11 09:01:21 +08:00
    gitbook 不好用吗。。。
    balabalaguguji
        15
    balabalaguguji  
    OP
       2019-03-11 09:48:15 +08:00
    @Spoter #14 写 api 文档不适合
    feehey
        16
    feehey  
       2019-03-11 10:01:54 +08:00
    Yapi 真香
    balabalaguguji
        17
    balabalaguguji  
    OP
       2019-03-11 10:56:59 +08:00
    @x86 #13 google 也在用 xyz
    nzzzg
        18
    nzzzg  
       2019-03-11 12:14:05 +08:00
    页面挂了? 进去是个空白页面
    wzw
        19
    wzw  
       2019-03-11 12:15:16 +08:00 via iPhone
    @feehey #16 同意
    balabalaguguji
        20
    balabalaguguji  
    OP
       2019-03-11 12:36:41 +08:00
    @nzzzg 什么浏览器,我们不支持 IE
    jigi330
        21
    jigi330  
       2019-03-11 12:41:43 +08:00 via Android
    挺好看的呀,回头试试
    balabalaguguji
        22
    balabalaguguji  
    OP
       2019-03-11 12:44:46 +08:00
    @feehey
    @wzw
    只支持一层目录结构,子参数也只有 2 层,编写体验不够好,每添加一行都要鼠标点击,预览不够优雅
    不支持自定义参数块,比如我想在请求参数后面增加一个请求说明;在响应参数那里多添加一个失败情况的返回参数块,或者调整参数块的顺序,不够灵活,而这些易文档都支持。
    ericv
        23
    ericv  
       2019-03-11 12:44:55 +08:00
    postman 足够了。。。
    balabalaguguji
        24
    balabalaguguji  
    OP
       2019-03-11 12:46:50 +08:00
    @ericv postman 主要只做接口测试这块的,文档功能很差,我们是文档+测试+测试用例+mock 一体,写完文档可以直接测试,测试完可以直接保存作为 demo,服务端还没开发好接口还可以一键生成 mock 配置,不影响客户端开发
    wzw
        25
    wzw  
       2019-03-11 12:48:13 +08:00
    @balabalaguguji #22 那自动化测试 方面呢
    w516322644
        26
    w516322644  
       2019-03-11 12:48:39 +08:00
    YAPI?
    balabalaguguji
        27
    balabalaguguji  
    OP
       2019-03-11 12:50:08 +08:00
    @wzw #25 这个还在排期开发中,后面会提供
    yixiang
        28
    yixiang  
       2019-03-11 12:51:49 +08:00
    竞品太多,还都免费,不知能盈利否。
    balabalaguguji
        29
    balabalaguguji  
    OP
       2019-03-11 12:56:49 +08:00
    @yixiang #28 当初也是为了自己方便开发的,后面越做越好,就成了产品,说实话,我们现在做的体验是市面第一的,不怕竞争。
    laogui
        30
    laogui  
       2019-03-11 13:04:25 +08:00 via Android
    xyz 域名感觉是那种过几天就打不开的网站
    jabin88
        31
    jabin88  
       2019-03-11 14:08:09 +08:00
    没感觉比其他竞品好,还收费
    chennqqi
        32
    chennqqi  
       2019-03-11 16:15:09 +08:00
    https://app.swaggerhub.com 个人用户免费,github 登录,可以公开可以私有,没发现比这个更好的;
    楼主可以对照一下
    edsheeran
        33
    edsheeran  
       2019-03-11 16:18:24 +08:00 via iPhone
    balabalaguguji
        34
    balabalaguguji  
    OP
       2019-03-11 16:22:57 +08:00
    @chennqqi #32 这个我们对比过了,远没我们的好,我们的个人用户也是免费
    lqzhgood
        35
    lqzhgood  
       2019-03-11 16:28:04 +08:00
    刚好做完一个个人项目~ 试用一下。
    lz 加油哦
    lqzhgood
        36
    lqzhgood  
       2019-03-11 16:35:20 +08:00
    接口描述 我感觉这样排列比较好~

    是否必须 参数类型 参数名 描述

    前面 2 个 宽度基本是一定的。 描述也许会很长。 这样比较对仗工整。

    是否必须 使用 ( 是 /否 ) 或者 多选框的勾选 来显示。 比较干净。
    chennqqi
        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 了,国内访问奇慢无比,但就是没找到更好的。
    balabalaguguji
        38
    balabalaguguji  
    OP
       2019-03-11 16:51:51 +08:00
    @chennqqi #37 你说的规范,那都是数据的格式了,写个脚本转换下就可以了。但是对于用户来说,我们更需要关注编写是否便捷,是否快速,预览时是否够清晰明了。你说的那个是直接写注释的,那种方式很麻烦,代码也会被严重污染,特别是参数多、有多层级参数返回时,一大片都是注释,这种跟写 txt 的感觉是一样的,建议你体验下我们的编写方式,完全不是一个级别的。
    chennqqi
        39
    chennqqi  
       2019-03-12 13:52:41 +08:00
    话不投机,就此打住
    LeonKennedy
        40
    LeonKennedy  
       2019-03-12 23:30:13 +08:00
    歪个题,网站前端用什么做的,服务条款那个页面好漂亮啊,正好有需要拿来用了
    balabalaguguji
        41
    balabalaguguji  
    OP
       2019-03-13 09:59:49 +08:00
    @LeonKennedy #用 vuejs+elementui
    aliangddd
        42
    aliangddd  
       2019-05-16 19:41:05 +08:00 via iPhone
    看着不错
    dNib9U2o8x
        43
    dNib9U2o8x  
       2019-05-29 23:18:58 +08:00
    免费版限制成员和文档数量没问题,但是导入导出都必须付费,这个是不是有点过分了?
    balabalaguguji
        44
    balabalaguguji  
    OP
       2019-05-30 18:31:32 +08:00
    @dNib9U2o8x #43 你得看看别人付出了多少,你又贡献了什么,为什么导入导出付费就过分了?
    dNib9U2o8x
        45
    dNib9U2o8x  
       2019-05-30 19:00:04 +08:00
    @balabalaguguji #44 我作为一个用户需要贡献什么?没有试用上来就充值?本来是要测试下效果,打算导入 swagger 或 postman 看看兼容情况,发现导入要收费,也就没有继续尝试的欲望了
    balabalaguguji
        46
    balabalaguguji  
    OP
       2019-05-31 12:40:35 +08:00
    @dNib9U2o8x 我们的免费版本实际上是很足够用的,免费额度很大;导入 swagger 和 postman 还没支持,如果支持了,这种导入肯定会是免费的。
    playscforever
        47
    playscforever  
       2019-07-18 22:56:02 +08:00
    支持~
    NicholasHsiang
        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。
    balabalaguguji
        49
    balabalaguguji  
    OP
       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
        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 开源,否则一般团队应该是不敢用的。
    anankun
        51
    anankun  
       2021-03-25 11:40:56 +08:00
    私有化部署的刚需,没有这个功能的很难能纳入考虑。
    balabalaguguji
        52
    balabalaguguji  
    OP
       2021-03-25 13:34:00 +08:00
    @anankun #51 私有部署是收费的
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1183 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 18:34 · PVG 02:34 · LAX 10:34 · JFK 13:34
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.