V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
MrXiong
V2EX  ›  Java

请问各位,公司内部的接口文档是怎么管理的?

  •  2
     
  •   MrXiong · 2017-09-12 19:48:51 +08:00 · 18165 次点击
    这是一个创建于 2389 天前的主题,其中的信息可能已经有所发展或是发生改变。
    1. 公司准备使用 swagger,基于注解的方式,但是发现多个项目无法集成,很不方便
    2. swagger-ui 中没有接口的搜索功能

    请问各位还有啥比较好用的轮子?

    第 1 条附言  ·  2017-09-12 20:39:50 +08:00
    @All 各位别搞我啊,得讲道理,我就不信大公司也是口口相传的?
    第 2 条附言  ·  2017-09-13 18:17:44 +08:00
    看到各位的回复,我也是放心了!当我在接手别人代码的时候的心情也能平复下了!
    119 条回复    2018-11-29 20:23:15 +08:00
    1  2  
    shenhb
        101
    shenhb  
       2017-09-13 16:43:36 +08:00
    RAP 呀!!
    duan602728596
        102
    duan602728596  
       2017-09-13 22:44:43 +08:00 via iPhone
    接口全靠猜
    xrlin
        103
    xrlin  
       2017-09-14 01:26:32 +08:00 via Android
    接口文档?不存在的
    Wuxj
        104
    Wuxj  
       2017-09-14 09:01:12 +08:00
    swagger +1
    workwonder
        105
    workwonder  
       2017-09-14 09:06:58 +08:00 via Android
    没人像我一样使用 insomnia 制作一份 API 调用示例导出给对接者直接调教吗?
    https://insomnia.rest
    Platycodon
        106
    Platycodon  
       2017-09-14 11:01:05 +08:00
    经历过三种
    swagger,rap,口口相传
    SEARCHINGFREE
        107
    SEARCHINGFREE  
       2017-09-14 15:13:42 +08:00
    接口文档.txt
    接口接口 2.txt
    caoyangmin
        108
    caoyangmin  
       2017-09-15 08:37:40 +08:00
    推荐 PhpBoot ( https://github.com/caoym/phpboot/blob/master/README.zh.md ),可以很方便的生成在线文档(swagger),且实时同步,关键还不需要像 swagger-php 一样加入很多额外的注释, 这是在线 demo: http://swagger.phpboot.org/?url=http%3A%2F%2Fexample.phpboot.org%2Fdocs%2Fswagger.json

    我就职过多两家公司都在用。
    caoyangmin
        109
    caoyangmin  
       2017-09-15 08:46:27 +08:00
    呃,我好像发错地方了
    sun5244725
        110
    sun5244725  
       2017-09-15 11:11:59 +08:00
    我们一般用 QQ 忘了就去找聊天记录
    kim2x
        111
    kim2x  
       2017-09-15 22:18:58 +08:00 via iPhone
    接口更新的时候口口相传就乏力了。swagger 最大的 bug 就是污染代码 本人觉得极其恶心🤢 楼上有说 confluence 没用过 我是用 gitbook😆😆😆
    MrXiong
        112
    MrXiong  
    OP
       2017-09-15 22:49:40 +08:00
    @kim2x 我觉得污染代码还好吧,毕竟本来代码就需要注释,只是现在多了点
    kim2x
        113
    kim2x  
       2017-09-16 12:40:51 +08:00 via iPhone
    @MrXiong 我感受到了 swagger 代码污染的恶心 个人无法接受 多余的注释加上 swagger 太乱了 重度污染
    leaybc
        114
    leaybc  
       2017-09-18 11:49:42 +08:00
    @MrXiong 开源中国里面有个 swagger bootstrap ui 这个还行
    wyk52012
        115
    wyk52012  
       2017-09-21 10:57:37 +08:00
    写 WIKI 文档=。=
    每个 API 都要写, 改动了也得改 API。
    251804746
        116
    251804746  
       2017-09-28 09:27:30 +08:00
    没有用 Postman 的吗, Postman 现在也支持 Markdown 文档了
    zhangv
        117
    zhangv  
       2018-01-02 11:32:24 +08:00
    说到底,任何文档解决的都是沟通问题。
    最完美的情况是:写文档( word/wiki/markdown )。但考虑到各种维护更新成本,几乎到最后都是“破窗效应” - 无疾而终。
    所以还是用工具,一来规范统一,二来维护成本低。
    如果是公司内部,有时候需要考虑遗留系统的情况,可能集成起来很复杂。这种情况下,我不觉得一个“全局”的解决方案是好的,因为影响范围过大,过剧烈。

    我比较喜欢 swagger,基于规范和维护成本的原因,当然 swagger 的规范也需要学习一下,比 markdown 多了规范 - 无论是其他人还是后来人都可以 follow,不至于改的面目全非或者后来者有“推翻重来”的冲动。而且因为是规范,不同语言都可以用。

    有人觉得 swagger 会“污染”代码,但如果把文档注释也当作代码的一部分,也就是不会觉得是污染了。
    rainbirda
        118
    rainbirda  
       2018-08-08 22:42:07 +08:00
    之前公司用的是 word+clearcase,类似 SVN 版本管理工具,目前公司用的是自己推荐的 dokuwiki,虽然页面古老,使用也不那么方便,但是配合各种插件,功能还是很强大的。
    balabalaguguji
        119
    balabalaguguji  
       2018-11-29 20:23:15 +08:00
    推荐你试下 https://easydoc.xyz 编写和预览的体验都很好
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1909 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 31ms · UTC 16:25 · PVG 00:25 · LAX 09:25 · JFK 12:25
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.