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

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

  •  2
     
  •   MrXiong · 2017-09-12 19:48:51 +08:00 · 18649 次点击
    这是一个创建于 2630 天前的主题,其中的信息可能已经有所发展或是发生改变。
    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  
    byuc
        1
    byuc  
       2017-09-12 19:53:08 +08:00
    口口相传
    qinxi
        2
    qinxi  
       2017-09-12 19:53:50 +08:00
    yoa1q7y
        3
    yoa1q7y  
       2017-09-12 19:56:25 +08:00
    口口相传+1
    sudoz
        4
    sudoz  
       2017-09-12 19:56:51 +08:00
    confluence
    Hypn0s
        5
    Hypn0s  
       2017-09-12 19:59:42 +08:00
    confluence + 1
    gaayyy
        6
    gaayyy  
       2017-09-12 20:03:59 +08:00
    靠猜
    nieyujiang
        7
    nieyujiang  
       2017-09-12 20:04:10 +08:00
    给你一个眼神,自己体会.🌚
    fengxuejianshi
        8
    fengxuejianshi  
       2017-09-12 20:18:15 +08:00 via iPhone
    意念
    aaxcc
        9
    aaxcc  
       2017-09-12 20:33:59 +08:00 via iPhone
    当然是打印出来贴在公司大门上,每天程序猿进门背一个借口,背错的扣工资
    cutlove
        10
    cutlove  
       2017-09-12 20:43:57 +08:00
    apizza
    irgil
        11
    irgil  
       2017-09-12 20:45:40 +08:00
    swagger,或者公司自研的。
    orancho
        12
    orancho  
       2017-09-12 20:47:17 +08:00
    protobuf / grpc 的 proto 文件
    MrXiong
        13
    MrXiong  
    OP
       2017-09-12 20:51:46 +08:00
    @irgil swagger 有什么使用姿势
    irgil
        14
    irgil  
       2017-09-12 21:28:12 +08:00
    @MrXiong 主要是自动生成文档,自动生成代码
    AndyJia
        15
    AndyJia  
       2017-09-12 22:23:45 +08:00 via Android
    openapi
    gemini
        16
    gemini  
       2017-09-12 22:29:09 +08:00
    word 文档不挺好的么
    iyaozhen
        17
    iyaozhen  
       2017-09-12 22:30:12 +08:00 via Android
    wiki,先定接口再开发
    crossoverJie
        18
    crossoverJie  
       2017-09-12 22:31:43 +08:00
    之前 confluence 现在 swagger
    hasbug
        19
    hasbug  
       2017-09-12 22:43:24 +08:00
    口口相传+1
    m939594960
        20
    m939594960  
       2017-09-12 22:44:40 +08:00
    gitlab 的 wiki 功能
    gy911201
        21
    gy911201  
       2017-09-12 23:13:16 +08:00
    口口相传
    fbzl
        22
    fbzl  
       2017-09-13 00:15:48 +08:00 via iPhone
    口口相传,心灵感应
    lgh
        23
    lgh  
       2017-09-13 00:28:47 +08:00 via iPhone
    @orancho #12 顺便问个相关的问题:pb 只能体现接口报文格式,你们是怎样管理 pb 和实际接口之间的关联关系这些信息的?
    Jackeriss
        24
    Jackeriss  
       2017-09-13 01:02:57 +08:00 via iPhone
    这个全看悟性
    junbguistar
        25
    junbguistar  
       2017-09-13 01:12:15 +08:00
    接口多就自己搭 wiki 和 swagger 少就口口相传
    49degree
        26
    49degree  
       2017-09-13 01:13:42 +08:00
    RAP
    fan123199
        27
    fan123199  
       2017-09-13 01:14:59 +08:00
    word 文档
    Lucups
        28
    Lucups  
       2017-09-13 01:19:33 +08:00
    不同方式的文档都有各自的优劣和使用场景,我主要考虑沟通成本,哪种方式沟通成本小用哪种。
    目前在公司用 confluence 手写,一个接口一个页面,其他部门人来要时直接丢链接。

    PS:Swagger 默认的 UI 不是很好用。有同感的可以考虑这个项目 https://github.com/jensoleg/swagger-ui。
    Lucups
        29
    Lucups  
       2017-09-13 01:20:18 +08:00
    我晕,加了空格还是把句号和链接合在一起了。。。重新补一下:

    https://github.com/jensoleg/swagger-ui
    Tyrion
        30
    Tyrion  
       2017-09-13 02:12:31 +08:00
    confluence + 1
    bombless
        31
    bombless  
       2017-09-13 02:24:17 +08:00 via Android
    写代码注释里面的,靠自觉,很多人不写的。

    听说大公司都是靠口口相传
    feiyuanqiu
        32
    feiyuanqiu  
       2017-09-13 03:18:32 +08:00 via Android
    @Lucups 我最近刚好在改这个 ui。它有个问题是把接口参数放在 div 的属性里,导致没法选择及复制,而且参数名长一点的话就显示不全。另外我也不太喜欢它调用接口时单独弹出一个 modal 的方式
    msg7086
        33
    msg7086  
       2017-09-13 07:33:02 +08:00
    早已失传……
    motai
        34
    motai  
       2017-09-13 08:13:53 +08:00 via iPhone
    rap,word,内部的 wiki 系统
    xtaxcy
        35
    xtaxcy  
       2017-09-13 08:18:46 +08:00 via Android
    小幺鸡
    caijihui11
        36
    caijihui11  
       2017-09-13 08:37:49 +08:00
    apidoc
    NSAtools
        37
    NSAtools  
       2017-09-13 08:39:03 +08:00
    口口相传
    icycai
        38
    icycai  
       2017-09-13 08:53:06 +08:00 via Android
    口口相传+1
    kindjeff
        39
    kindjeff  
       2017-09-13 08:57:43 +08:00 via iPhone
    传嫡不传庶,传长不传幼,传男不传女
    justicelove
        40
    justicelove  
       2017-09-13 09:01:48 +08:00
    搜索就是 control + F
    caizhendi
        41
    caizhendi  
       2017-09-13 09:13:38 +08:00
    后台自己维护个文档
    cnbattle
        42
    cnbattle  
       2017-09-13 09:15:02 +08:00
    口口相传.gif
    simonlu9
        43
    simonlu9  
       2017-09-13 09:16:24 +08:00
    eo-linker
    chocotan
        44
    chocotan  
       2017-09-13 09:17:18 +08:00
    一开始是口口相传,自从搭了 confluence 后大多用这个了
    Clarencep
        45
    Clarencep  
       2017-09-13 09:19:11 +08:00
    我司是我自己用 Laravel 写了一个基于 Markdown 的文档系统,支持文档模版,支持复制粘贴图片,支持全文检索,支持用户权限管理。开发用时约 3 天。

    话说这种东西还是自己做的用着舒服:)

    上家用的 confluence 也很不错,不过现在这家没买,懒得搞破解版,所以还是自己动手丰衣足食。
    lrh3321
        46
    lrh3321  
       2017-09-13 09:20:48 +08:00
    口口相传+1

    忘记了就去看聊天记录
    timelessg
        47
    timelessg  
       2017-09-13 09:29:45 +08:00 via Android
    当然是微信了
    vlean
        48
    vlean  
       2017-09-13 09:42:46 +08:00
    @49degree RAP+1 +wiki
    a7063888
        49
    a7063888  
       2017-09-13 09:47:21 +08:00
    @lrh3321
    口口相传+聊天记录 还是老哥稳

    公司用 confluence
    keepcleargas
        50
    keepcleargas  
       2017-09-13 10:35:01 +08:00
    slate + git
    xiaowangge
        51
    xiaowangge  
       2017-09-13 10:40:27 +08:00
    口口相传+聊天记录

    +1
    vjnjc
        52
    vjnjc  
       2017-09-13 10:40:29 +08:00
    wiki +1
    swagger 的话不用他一整套不方便吧,还不如 wiki 上格式写规范点
    teaaa
        53
    teaaa  
       2017-09-13 10:43:50 +08:00
    wiki +1
    强迫症觉得必须有统一的接口文档啊
    很方便高效啊
    要不怎么推锅
    WendellSun
        54
    WendellSun  
       2017-09-13 10:44:11 +08:00
    口口相传+1
    noNOno
        55
    noNOno  
       2017-09-13 10:45:55 +08:00
    confluence + 1
    imherer
        56
    imherer  
       2017-09-13 10:46:18 +08:00
    https://github.com/lord/slate 这个。支持搜索
    codeyung
        57
    codeyung  
       2017-09-13 10:47:41 +08:00
    confluence 自写(之前项目都是自己 wiki 手写的 很多 ) 现在的 swagger 做模块服务时候用
    fork3rt
        58
    fork3rt  
       2017-09-13 10:51:51 +08:00
    swagger 或者 手写 markdown
    liuqitoday
        59
    liuqitoday  
       2017-09-13 11:20:08 +08:00
    口口相传+1
    YiBaZhuangYuan
        60
    YiBaZhuangYuan  
       2017-09-13 11:22:50 +08:00
    GitLab
    my3157
        61
    my3157  
       2017-09-13 11:24:23 +08:00
    昨天正好也在看这个, 转了一圈, 目前做 api 文档管理的有 nei easyapi eolinker apizza RAP , 体验了其中 eolinker 和 apizza, 最后选择了 postman, 不但能做文档, 顺便还写了 api 测试 , 免费档已够用
    lifeforwater
        62
    lifeforwater  
       2017-09-13 11:31:41 +08:00
    小幺鸡
    zjsxwc
        63
    zjsxwc  
       2017-09-13 11:33:51 +08:00 via Android
    邮件
    xxdd
        64
    xxdd  
       2017-09-13 11:44:08 +08:00
    看我口型
    orancho
        65
    orancho  
       2017-09-13 11:53:53 +08:00
    @lgh

    如果你用 gRPC 的话,可以直接将 proto 文件中定义的 service 名传给 invoke 函数。对于使用 protobuf 的 RESTful API,我司一般的方法是在对应的 message 前的注释中写上对应的 URI。
    leaybc
        66
    leaybc  
       2017-09-13 11:58:02 +08:00
    我在用 swagger 然后配合第三方的 UI . 感觉挺好的
    silov
        67
    silov  
       2017-09-13 12:01:18 +08:00
    markdown 丢 git 上 ==
    Simcyber
        68
    Simcyber  
       2017-09-13 12:30:31 +08:00
    口口相传+1024
    MrXiong
        69
    MrXiong  
    OP
       2017-09-13 12:42:58 +08:00
    @leaybc 有啥 ui 推荐
    ezreal
        70
    ezreal  
       2017-09-13 12:52:06 +08:00 via iPhone
    口口相传
    laudukang
        71
    laudukang  
       2017-09-13 13:00:38 +08:00
    口口相传
    Vindroid
        72
    Vindroid  
       2017-09-13 13:02:24 +08:00
    GitLab
    qscqesze
        73
    qscqesze  
       2017-09-13 13:03:48 +08:00
    口口相传,最多写个 wiki 解释一下
    zhygkx
        74
    zhygkx  
       2017-09-13 13:06:48 +08:00
    dreamwar
        75
    dreamwar  
       2017-09-13 13:08:49 +08:00
    心灵感应
    owenliang
        76
    owenliang  
       2017-09-13 13:09:46 +08:00
    gitlab README
    c0878
        77
    c0878  
       2017-09-13 13:12:23 +08:00
    mkdocs
    l00t
        78
    l00t  
       2017-09-13 13:17:19 +08:00
    Excel + svn
    siteshen
        79
    siteshen  
       2017-09-13 13:27:44 +08:00
    我们公司使用的 swagger,不过默认的“先设计好 *所有* API 格式,再生成代码模版”的方式并不适合我们(因为随时需要增加新的 API 和扩展现有的 API ),我们的使用方式如下:

    1. python/go 代码按正常逻辑写,如:
    // method, url, input format, output format
    routes = [("POST", "/me/update", UpdateMeForm, MeResponse, ["tag1", "tag2", ...])]

    2. 自定义函数 ToSwaggerJSON(method, url, request_form, response_object) 生成对应的 swagger.json 文件,然后交给 swagger-ui 处理其余事情;

    3. 客户端在浏览器查看 API 文档,几乎没有进行过 API 问题的沟通。

    ps: 最大的难点在于 ToSwagger() 函数,python/go 都没找到合适的库,花了不少的时间(印象中 python/go 各一周?),自己查看 swagger 文档实现了部分接口格式。
    Lucups
        80
    Lucups  
       2017-09-13 13:29:52 +08:00
    @feiyuanqiu 改好了提 pull request 回馈社区~~
    mahengyang
        81
    mahengyang  
       2017-09-13 13:56:00 +08:00
    多个接口之间的关系怎么体现呢?
    janus77
        82
    janus77  
       2017-09-13 14:00:09 +08:00
    RAP 啊
    luili
        83
    luili  
       2017-09-13 14:02:37 +08:00
    confluence
    tjxiter
        84
    tjxiter  
       2017-09-13 14:08:48 +08:00
    口口相传+1
    darklh
        85
    darklh  
       2017-09-13 14:27:13 +08:00
    前公司用 rap
    zpf124
        86
    zpf124  
       2017-09-13 14:29:49 +08:00
    前段时间我们要补文档,找了半天最终用了 swagger。

    话说当时还看到一个 Read The Docs 不知道有没有人用这个
    acros
        87
    acros  
       2017-09-13 14:34:11 +08:00
    口口相传的各位····
    兼职公司吟游诗人职位吗?
    JustCJ
        88
    JustCJ  
       2017-09-13 14:45:34 +08:00
    slate
    MushishiXian
        89
    MushishiXian  
       2017-09-13 15:14:21 +08:00
    有时候更新了文档还是要去通知下,通知过程中可能就直接说改了哪里,也可能就是口口相传了,网易那个 nei 不知道怎样,体验了下感觉还行
    v2chou
        90
    v2chou  
       2017-09-13 15:15:06 +08:00
    给你一个眼神,自己体会
    zhouyou457
        91
    zhouyou457  
       2017-09-13 15:20:30 +08:00
    正常情况下写 md,然后导出 pdf 放 svn 上。。

    紧急情况下,口口相传,记不清的自己看聊天记录[doge]
    ming7435
        92
    ming7435  
       2017-09-13 15:26:49 +08:00
    @49degree RAP+1
    xjmroot
        93
    xjmroot  
       2017-09-13 15:30:55 +08:00
    xjmroot
        94
    xjmroot  
       2017-09-13 15:32:40 +08:00   ❤️ 1
    公司内部部署个,超级简单,还能导出 word
    https://github.com/star7th/showdoc
    teaaa
        95
    teaaa  
       2017-09-13 15:36:45 +08:00
    dokuwiki 也很好用啊 可以自动生成目录
    Wysten
        96
    Wysten  
       2017-09-13 15:36:59 +08:00
    眼神体会
    kk941kk
        97
    kk941kk  
       2017-09-13 15:43:53 +08:00
    没有文档,不用管理。。
    jadec0der
        98
    jadec0der  
       2017-09-13 16:37:12 +08:00
    thrift / confluence ( http)
    SvenWong
        99
    SvenWong  
       2017-09-13 16:41:04 +08:00
    口口相传 +1
    Hilong
        100
    Hilong  
       2017-09-13 16:41:59 +08:00 via Android
    300 多个接口,没有文档,就一个 postman 调用事例,然后口口相传
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2970 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 31ms · UTC 12:47 · PVG 20:47 · LAX 04:47 · JFK 07:47
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.