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

我们出新产品啦,专业漂亮的 API 文档系统

  •  
  •   balabalaguguji · 2018-11-20 10:43:59 +08:00 · 8345 次点击
    这是一个创建于 2231 天前的主题,其中的信息可能已经有所发展或是发生改变。

    我是技术出生的,一直梦想自己能做点产品出来,不过我想到的产品都是跟技术相关的,这类产品一般属于小众,也赚不到什么钱,所以一般很少人去做好它,但是作为一个技术人员的情怀,我觉得有必要去用心做好它,创业一年多了,终于我们上新产品啦。这次我们要解救开发人员编写文档的痛苦。

    我们的产品叫易文档: https://easydoc.xyz ,支持在线接口测试、自定义文档模板、预定义常用参数、分享文档。现在还是 beta 版,可能存在一些问题,大家可以跟我们反馈,我们会进行完善升级。

    为什么我会选择做这个? 我们公司是外包+自研产品模式,经常需要些一些接口文档和使用手册,网上找过很多个,都不满意,所以我们决定自己做一套了。

    我见过很多公司写接口文档还在用 word,excel,txt,要我用这种写接口文档,我是很痛苦的,首先是编写起来很麻烦,格式要编排好很费力,出来的文档也不漂亮,查找接口又麻烦,另外每次修改了一点东西,都要重新同步给协作者。 当然还有的公司直接就文档都不写,两个人直接坐在一起开发,直接口头传播,当然没问题,但是如果下个人接手你的项目,他就得看代码去了解接口有哪些参数了。

    欢迎大家体验,给我们提建议,我们的目标是做最好的用的在线文档管理系统

    第 1 条附言  ·  2018-11-20 13:14:02 +08:00
    第三方登录已经改为直接进入了
    第 2 条附言  ·  2018-11-21 13:14:58 +08:00
    有人说为什么我们要重复造轮子,因为现在的轮子不够好,不满足我们的高要求。
    我们做过很多调查,API 文档这块,体验做的好的,符合要求的,我是一个都没找到。
    我说下我们对 API 文档的要求:
    1.编写体验要好,不需要动鼠标,写完一个 tab 一下就下一个
    2.支持参数行顺序调整,拖动就能调整
    3.支持子参数,因为参数经常是有字典类型的
    4.可以随意增加 /删除参数块,比如我不需要头部参数,我可以删除;我可以添加成功时返回什么参数,失败时又返回什么参数
    5.可以自定义说明,比如我想在请求参数后面添加一个特别说明,或者示例,我可以随时增减,并且随时调整顺序
    6.可以在线测试接口
    7.预览页要很漂亮,点击就能自动复制 url,参数名等
    8.文档列表可以进行分类,调整顺序,搜索
    9.可以随时分享文档给朋友,可以设置密码、失效时间
    10.完成开发后,还需要支持写部署文档,使用手册

    以上我们说的要求,你们要是能找到任何一个其他文档系统能满足,算我输。
    我们的文档系统是全部满足以上要求的,因为我自己是做开发的,对这类产品的理解比较深,要求也比较高,希望开发人员能有个更好的文档体验
    77 条回复    2018-11-27 19:36:30 +08:00
    scofieldpeng
        1
    scofieldpeng  
       2018-11-20 10:57:09 +08:00
    建议出一个开源自部署,可能还会火
    Tierney
        2
    Tierney  
       2018-11-20 11:01:02 +08:00
    友情帮顶+1,看起来很舒服
    Chappako
        3
    Chappako  
       2018-11-20 11:09:13 +08:00
    支持一下,加油
    anakinsky
        4
    anakinsky  
       2018-11-20 11:12:38 +08:00
    🐮B 顶一下
    twor
        5
    twor  
       2018-11-20 11:13:40 +08:00
    预览有 bug ? 点击没有内容
    yuedingwangji
        6
    yuedingwangji  
       2018-11-20 11:13:42 +08:00
    看起来不错, 跟 yapi 比起来有什么特点么
    CopyRight
        7
    CopyRight  
       2018-11-20 11:13:57 +08:00
    秒关了三方登录授权成功后的页面。
    qiayue
        8
    qiayue  
       2018-11-20 11:14:35 +08:00
    去掉测试功能,或者测试功能改成可配置为用户自己的测试环境接口,然后收费(或免费)提供可以自部署安装版本
    nekoneko
        9
    nekoneko  
       2018-11-20 11:16:17 +08:00
    不错,能自部署会更好
    balabalaguguji
        10
    balabalaguguji  
    OP
       2018-11-20 11:17:31 +08:00
    @scofieldpeng #1 等我们产品完善好后,会提供免费私有部署版本的
    wispx
        11
    wispx  
       2018-11-20 11:20:26 +08:00
    看着还可以
    balabalaguguji
        12
    balabalaguguji  
    OP
       2018-11-20 11:22:22 +08:00
    @yuedingwangji #6 我们比他们更加专业,编写体验更好,预览更漂亮
    fengpan567
        13
    fengpan567  
       2018-11-20 11:22:42 +08:00
    为什么用 QQ 登录了还要绑定邮箱。、。。。。。。。。
    kulove
        14
    kulove  
       2018-11-20 11:23:24 +08:00
    xyz 这后缀..看着就感觉不专业..没有 com cn,也不能用 xyz 吧..
    balabalaguguji
        15
    balabalaguguji  
    OP
       2018-11-20 11:24:27 +08:00
    @fengpan567 #13 因为邮箱是用来添加好友用的,不设置邮箱不好找人
    zhangalong69
        16
    zhangalong69  
       2018-11-20 11:33:01 +08:00
    为什么微信登录了还要绑邮箱设置密码呀,这一步会劝退不少人
    lepig
        17
    lepig  
       2018-11-20 11:38:48 +08:00
    别用 xyz, 真的很业余。
    balabalaguguji
        18
    balabalaguguji  
    OP
       2018-11-20 11:40:10 +08:00
    @zhangalong69 #16 嗯,刚开始是考虑到要添加成员时需要用邮箱来查找,我们稍后去掉这步
    zifangsky
        19
    zifangsky  
       2018-11-20 11:41:17 +08:00
    看了一下,功能界面都挺好,不过一些明显的 BUG 后面还要再改改,另外提个建议:写好的文档可以导出成 PDF 离线文档。
    lniwn
        20
    lniwn  
       2018-11-20 11:50:03 +08:00
    简单体验了下,最大的感受就是登陆过程一头雾水,明明用微信提示登陆成功了,结果还弹出帐号密码界面。不过界面和内容不错,慢慢完善,应该是个不错的产品。
    CEBBCAT
        21
    CEBBCAT  
       2018-11-20 11:57:21 +08:00 via Android
    又是一个被发帖 bug 坑到发错节点的帖子 @Livid
    Livid
        22
    Livid  
    MOD
       2018-11-20 12:00:06 +08:00 via iPhone
    @CEBBCAT 什么 bug ?能否稍微描述一下?
    Livid
        23
    Livid  
    MOD
       2018-11-20 12:00:25 +08:00 via iPhone
    aaronnum7
        24
    aaronnum7  
       2018-11-20 12:02:08 +08:00
    文档里面,表格的下边框和表头阴影没有对齐,有点强迫症。。。
    balabalaguguji
        25
    balabalaguguji  
    OP
       2018-11-20 12:07:17 +08:00
    @Livid 我想把它放在分享创造那里的
    Cbdy
        26
    Cbdy  
       2018-11-20 12:09:58 +08:00 via Android
    xyz,挺好的,也很专业,参考字母表公司
    建议兼容 swagger 的 api doc 标准
    megachweng
        27
    megachweng  
       2018-11-20 12:12:02 +08:00 via iPhone
    和小幺鸡比起来有什么优势
    duola
        28
    duola  
       2018-11-20 12:13:22 +08:00
    这个可以有,我试一下。
    balabalaguguji
        29
    balabalaguguji  
    OP
       2018-11-20 12:30:32 +08:00
    @megachweng #27 我们比小幺鸡体验好太多了,不管是编写体验还是预览,你试下就知道了
    longjiahui
        30
    longjiahui  
       2018-11-20 12:41:57 +08:00
    再把功能完善一下,非常不错!
    icella
        31
    icella  
       2018-11-20 12:54:39 +08:00 via Android
    敢问兄弟 你这个怎么跟 MinDoc 功能和长相都差不多呢 人家是开源的
    laike9m
        32
    laike9m  
       2018-11-20 12:58:02 +08:00 via Android
    出身,不是出生
    hash
        33
    hash  
       2018-11-20 13:00:37 +08:00
    看到说 xyz 域名业余,Alphabet 真是泪流满面.
    icella
        34
    icella  
       2018-11-20 13:07:27 +08:00 via Android
    @Chappako 建议看一下那个开源的 MinDoc 总感觉这个推广的跟人家一模一样😛
    balabalaguguji
        35
    balabalaguguji  
    OP
       2018-11-20 13:16:54 +08:00
    @icella #31 你认真看下我们的,对比下,我们的可以说各方面都比你说的 MinDoc 做的更优秀
    Kilerd
        36
    Kilerd  
       2018-11-20 13:20:28 +08:00
    那个蓝色的边栏,真的不是抄袭 readthedocs 吗?
    icella
        37
    icella  
       2018-11-20 13:39:44 +08:00 via Android
    @balabalaguguji 你就说是不是参考人家的吧
    Asimov01
        38
    Asimov01  
       2018-11-20 13:54:54 +08:00
    支持!!!
    icella
        39
    icella  
       2018-11-20 13:58:13 +08:00
    @Kilerd 整个功能还都是抄袭 MinDoc 呢 可是楼主一直不敢正面回答 呵呵
    balabalaguguji
        40
    balabalaguguji  
    OP
       2018-11-20 14:08:07 +08:00
    @icella #39 在你说这个 MinDoc 之前,我们都不知道有这个,我们有参考很多其他同类竞品,你说的这个确实不是我们的追求目标
    icella
        41
    icella  
       2018-11-20 14:33:48 +08:00
    @balabalaguguji 页面排版都一样,这么巧合
    balabalaguguji
        42
    balabalaguguji  
    OP
       2018-11-20 16:39:40 +08:00
    @zifangsky #19 导出离线文档的功能我们会在后面些时间提供
    balabalaguguji
        43
    balabalaguguji  
    OP
       2018-11-20 18:42:56 +08:00
    @lniwn 嗯,现在是收集大家反馈完善阶段,我们不断开发完善
    CEBBCAT
        44
    CEBBCAT  
       2018-11-21 01:18:38 +08:00 via Android
    @Livid #21 说不清,给一下复现步骤:

    1. 打开 /new
    2. 点击分享创造按钮(就是那个链接到 javascript:chooseNode('create') 的)

    这时候发现节点选成了 C/C++/Obj-C/c,复现完毕

    说实话,这是老 bug 了,很老很老。一起想反映的还有节点选单不全的问题。20 号凌晨( CST ),我试着在反馈节点下发帖,被告知发主题帖间隔要大于 10 分钟,从 FAQ 找到 support 那个邮箱之后,心又很累,就没有发邮件

    当然了,若是你或者其他我不知道存在不存在的开发人员没有时间,那可以适当延后,因为最近 V2EX 似乎没有改变

    以上是一个普通用户在凌晨敲下的反馈,可能有点语气低落,抱歉
    以上
    CEBBCAT
        45
    CEBBCAT  
       2018-11-21 01:19:28 +08:00 via Android
    @CEBBCAT Emmm,说好十一点睡觉的,又被室友拖累了 doge
    Livid
        46
    Livid  
    MOD
       2018-11-21 02:47:40 +08:00 via iPhone
    @CEBBCAT 谢谢你的描述。初步猜测是节点名里的某个特殊字符导致的问题。我会去看看。目前,V2EX 的代码就是我一个人在写。作为一个两个孩子的父亲,时间确实很紧张。
    balabalaguguji
        47
    balabalaguguji  
    OP
       2018-11-21 09:46:20 +08:00
    @Livid 能否帮我恢复到分享创造那个分类呢,我是想发到那里去的,你这个 bug 导致错位了
    Livid
        48
    Livid  
    MOD
       2018-11-21 10:03:12 +08:00
    @balabalaguguji 已经移动。

    在主题最初发布的 10 分钟之内,如果对所在节点不满意,是可以自由移动的。
    xunqin
        49
    xunqin  
       2018-11-21 10:14:14 +08:00
    https://www.kancloud.cn/

    这种网站现在很多了
    hydyy
        50
    hydyy  
       2018-11-21 11:12:23 +08:00
    为啥要造这种轮子
    balabalaguguji
        51
    balabalaguguji  
    OP
       2018-11-21 12:55:47 +08:00
    @xunqin #49 看云我们知道,API 文档你有用过他的写吗?你对比下,我保证你会爱上我们这个,我们这个更加专注 HTTP 文档这些,编写和预览的体验都是超越所有竞品的。当然我们除了对 API 文档支持很好外,对使用手册这种也是支持很好的。
    balabalaguguji
        52
    balabalaguguji  
    OP
       2018-11-21 12:58:33 +08:00
    @hydyy #50 因为市面上没有任何一款产品能达到我们的要求,我们希望编写 API 文档的体验是畅快的,阅读是让人愉悦的。你能找出比我们体验更好的吗?
    kios
        53
    kios  
       2018-11-21 13:32:42 +08:00
    请问楼主这个和 readthedoc 有什么区别吗?
    edsheeran
        54
    edsheeran  
       2018-11-21 13:41:08 +08:00
    @kulove abc.xyz 打臉
    wuhai
        55
    wuhai  
       2018-11-21 15:09:19 +08:00
    技术出身的。。不是出生的。。
    sunny2580839896
        56
    sunny2580839896  
       2018-11-21 15:45:11 +08:00
    不可以解析 json,很烦
    hydyy
        57
    hydyy  
       2018-11-21 17:21:52 +08:00
    @balabalaguguji 目前用 https://yapi.ymfe.org/ 体验也是极好的
    balabalaguguji
        58
    balabalaguguji  
    OP
       2018-11-21 18:43:19 +08:00
    @sunny2580839896 #56 后面我们会支持
    balabalaguguji
        59
    balabalaguguji  
    OP
       2018-11-21 18:44:30 +08:00
    @kios #53 readthedoc 是直接用 markdown 的,写接口文档特麻烦,你用下就知道了
    nicoljiang
        60
    nicoljiang  
       2018-11-21 18:46:25 +08:00
    支持楼主创造。
    虽然我觉得 yapi 足够优秀漂亮了,而且可以私有化部署。
    balabalaguguji
        61
    balabalaguguji  
    OP
       2018-11-21 19:14:04 +08:00
    @nicoljiang #60 yapi 很多东西还没达到我们的高要求,对比用一下就知道,我们优势大很多
    Eugene1024
        62
    Eugene1024  
       2018-11-21 22:18:17 +08:00
    支持下
    qinxi
        63
    qinxi  
       2018-11-21 22:23:54 +08:00
    居然没有不需要登陆就能演示的 demo 页? 太差评了
    storypanda
        64
    storypanda  
       2018-11-22 00:00:54 +08:00 via Android
    @balabalaguguji 看官网是模仿的 git book ?首页需要好好设计一下
    balabalaguguji
        65
    balabalaguguji  
    OP
       2018-11-22 09:41:51 +08:00
    @qinxi #63 首页底部有 demo
    qinxi
        66
    qinxi  
       2018-11-22 09:52:19 +08:00
    @balabalaguguji #65 我说的演示是全套不用登录的,包括编辑和渲染。。你的 demo 是经过渲染之后的
    balabalaguguji
        67
    balabalaguguji  
    OP
       2018-11-22 10:06:45 +08:00
    @qinxi #66 不登录就编辑的暂时没有,另外登录非常简单了,第三方登录点击一下就进去了。
    levywang
        68
    levywang  
       2018-11-22 10:15:26 +08:00
    你好,非常好用。
    但是手机页面的适配不是很好,图片会溢出整个 body
    balabalaguguji
        69
    balabalaguguji  
    OP
       2018-11-22 10:19:56 +08:00
    @levywang #68 感谢支持,手机上还没做兼容,人手不够,先做好 PC 端,后面会完善手机端
    aqqwiyth
        70
    aqqwiyth  
       2018-11-22 13:03:13 +08:00
    接口测试在哪呢..
    sunny2580839896
        71
    sunny2580839896  
       2018-11-22 14:34:51 +08:00
    @balabalaguguji 那就太好了
    balabalaguguji
        72
    balabalaguguji  
    OP
       2018-11-22 15:01:30 +08:00
    @aqqwiyth #70 HTTP 文档编辑页面和预览页面都有
    M0
        73
    M0  
       2018-11-22 15:40:44 +08:00
    bug 反馈: 点击 A 文档后,向下滚动,页面停留在 x 位置,点击 B 文档,希望此时页面跳转到 B 文档的头部,但是页面会显示 B 文档的 x 位置。
    balabalaguguji
        74
    balabalaguguji  
    OP
       2018-11-23 09:49:16 +08:00
    @M0 #73 收到,最近我们会修复
    balabalaguguji
        75
    balabalaguguji  
    OP
       2018-11-23 12:06:52 +08:00
    @M0 #73 已修复
    SingeeKing
        76
    SingeeKing  
       2018-11-26 16:57:05 +08:00
    做得很好,希望什么时候有开源自部署了可以 At 一下我
    balabalaguguji
        77
    balabalaguguji  
    OP
       2018-11-27 19:36:30 +08:00
    @SingeeKing #76 好的
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2488 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 29ms · UTC 15:37 · PVG 23:37 · LAX 07:37 · JFK 10:37
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.