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

你们团队都是怎么管理 API 文档的

  •  
  •   jimyan ·
    sansanboy · 2017-02-16 08:34:41 +08:00 via iPad · 16292 次点击
    这是一个创建于 2597 天前的主题,其中的信息可能已经有所发展或是发生改变。

    api   文档是用 wiki 还是 doc

    第 1 条附言  ·  2017-02-16 11:08:06 +08:00
    除了 api 文档,还有需求设计文档。所以我的问题应该是怎么管理文档的,包括需求文档、设计文档、 api 文档等
    第 2 条附言  ·  2017-02-16 20:31:13 +08:00
    总结如下,后面再补充
    Swagger
    Confluence
    showdoc
    口头传述
    gitlab 传 md....
    天啦,还有 API 文档,没听说过
    raml
    wiki
    gogs
    apidoc
    quip
    意念传输
    postman
    RAP
    102 条回复    2019-10-30 18:58:30 +08:00
    1  2  
    yxzblue
        1
    yxzblue  
       2017-02-16 08:38:17 +08:00
    Swagger
    kancloud
        2
    kancloud  
       2017-02-16 08:43:13 +08:00
    用看云 可以支持 api 文档在线调试
    coldmn3
        3
    coldmn3  
       2017-02-16 08:58:04 +08:00
    用的 Confluence, 感觉还行吧,同求推荐。
    linkoubian
        4
    linkoubian  
       2017-02-16 09:00:31 +08:00
    @coldmn3 同样是 Confluence
    loadsome
        5
    loadsome  
       2017-02-16 09:03:44 +08:00 via iPhone
    小幺鸡
    Felldeadbird
        6
    Felldeadbird  
       2017-02-16 09:07:19 +08:00
    写工具反射得出 API 文档
    jimyan
        7
    jimyan  
    OP
       2017-02-16 09:14:43 +08:00 via Android
    @Felldeadbird 我们是先文档,除了 API 文档,还有设计文档等
    liyj144
        8
    liyj144  
       2017-02-16 09:24:44 +08:00
    daben1990
        9
    daben1990  
       2017-02-16 09:27:04 +08:00
    https://github.com/fyddaben/lettuce 我们用的 API Blueprint 语法,然后起了个 mock server ,
    SourceMan
        10
    SourceMan  
       2017-02-16 09:27:26 +08:00   ❤️ 7
    口头传述
    thanksir
        11
    thanksir  
       2017-02-16 09:27:26 +08:00
    推荐 showdoc ,这个还不错的
    chipmuck
        12
    chipmuck  
       2017-02-16 09:28:01 +08:00
    通过 gitlab 传 md....
    StevenTong
        13
    StevenTong  
       2017-02-16 09:28:27 +08:00
    swagger +1
    lifesimple
        14
    lifesimple  
       2017-02-16 09:29:54 +08:00
    swagger +2
    Abigale
        15
    Abigale  
       2017-02-16 09:31:14 +08:00
    没有。
    awolfly9
        16
    awolfly9  
       2017-02-16 09:31:16 +08:00
    天啦,还有 API 文档,没听说过
    superpeaser
        17
    superpeaser  
       2017-02-16 09:34:02 +08:00 via iPhone
    Confluence +1
    lijinma
        18
    lijinma  
       2017-02-16 09:35:07 +08:00
    raml
    Asan
        19
    Asan  
       2017-02-16 09:37:05 +08:00
    wiki
    wawehi
        20
    wawehi  
       2017-02-16 09:37:30 +08:00
    gogs 建个项目 传 .md 上去
    liyu001989
        21
    liyu001989  
       2017-02-16 09:38:37 +08:00
    odirus
        22
    odirus  
       2017-02-16 09:39:26 +08:00
    尝试过很多,不过现在都转入了 doc ,模板建立好之后,还是挺方便的。
    tjxiter
        23
    tjxiter  
       2017-02-16 09:41:58 +08:00
    没有 API 文档。。。
    PICKSOMETHING
        24
    PICKSOMETHING  
       2017-02-16 09:47:54 +08:00
    quip
    mcfog
        25
    mcfog  
       2017-02-16 09:54:51 +08:00
    内嵌在代码中,验证参数和展示文档调用同一个来源
    nashxk
        26
    nashxk  
       2017-02-16 10:11:45 +08:00
    confluence ,有个问题是,后来新增的很多字段,都会忘记更新上去。。而且支持 MarkDown 还需要安装插件好像。。
    solee
        27
    solee  
       2017-02-16 10:15:11 +08:00
    apidoc
    amon
        28
    amon  
       2017-02-16 10:39:15 +08:00
    markdown+gitlab
    ixiaozhi
        29
    ixiaozhi  
       2017-02-16 10:40:46 +08:00
    意念传输
    wmttom
        30
    wmttom  
       2017-02-16 10:46:50 +08:00
    Swagger +3
    代码生成文档,或者文档生成代码,一旦各自独立书写总会产生不一致。
    jimyan
        31
    jimyan  
    OP
       2017-02-16 10:48:33 +08:00 via Android
    @odirus doc 多人编辑和同步很麻烦。当然谷歌 doc 是可以的
    kaka8wp
        32
    kaka8wp  
       2017-02-16 10:56:33 +08:00
    swagger+1
    kenshinhu
        33
    kenshinhu  
       2017-02-16 10:57:00 +08:00   ❤️ 1
    我这边是在用 node 的 apidoc 。。。。。
    xwartz
        34
    xwartz  
       2017-02-16 10:59:20 +08:00
    postman
    settings
        35
    settings  
       2017-02-16 11:01:38 +08:00
    Swagger 可以在线调试,根据文档 API 还能反射出静态文档
    lc4t
        36
    lc4t  
       2017-02-16 11:08:38 +08:00 via iPhone
    swagger+quip
    MasterC
        37
    MasterC  
       2017-02-16 11:10:03 +08:00
    有道云协作 + markdown
    zyue
        38
    zyue  
       2017-02-16 11:12:37 +08:00   ❤️ 1
    使用 wiki 配合 jira 挺好用的
    klgd
        39
    klgd  
       2017-02-16 11:22:29 +08:00
    @yxzblue
    @StevenTong
    @lifesimple
    @wmttom
    @kaka8wp
    @settings
    @lc4t
    请教一下, swagger 有版本间的比较吗?
    lshero
        40
    lshero  
       2017-02-16 11:22:58 +08:00
    Confluence 编辑文档浏览器天天卡死
    zhuf
        41
    zhuf  
       2017-02-16 11:28:56 +08:00
    swagger+1
    mckelvin
        42
    mckelvin  
       2017-02-16 11:53:46 +08:00
    https://apiblueprint.org/ 用 atom 加插件写类似 Markdown 的语法,用 Aglio 渲染成 html 文档, 顺手用 Drakov 生成 mock server 方便前后端分离开发。
    kankana
        43
    kankana  
       2017-02-16 12:22:52 +08:00 via iPhone
    apizza.cc 用的是这个。 postman 后直接文档
    caixiexin
        44
    caixiexin  
       2017-02-16 12:26:24 +08:00 via Android
    用 swagger 可以保持接口跟文档同时更新,但是如果用接口生成文档的方式,源代码会有很多原来放在文档里的说明信息。
    不管哪种方式,写文档的工作是省不掉的😂
    firstfire
        45
    firstfire  
       2017-02-16 12:40:36 +08:00
    代码里用 Javadoc
    API 文档用 Markdown 写用 SVN 管理版本
    sobigfish
        46
    sobigfish  
       2017-02-16 12:47:47 +08:00
    OpenAPI / Swagger
    argon33
        47
    argon33  
       2017-02-16 13:02:25 +08:00
    文档的维护太难了。。。放在代码库里?
    settings
        48
    settings  
       2017-02-16 13:45:40 +08:00
    @klgd 版本间的比较指的是文档更新后的对比吗?
    geeksu
        49
    geeksu  
       2017-02-16 13:46:28 +08:00
    我们的 API 没有文档。。
    AJian
        50
    AJian  
       2017-02-16 14:29:14 +08:00
    用过 RAP
    Ixizi
        51
    Ixizi  
       2017-02-16 14:39:51 +08:00
    目前在用 RAP 虽然不喜欢 java
    Jackeriss
        52
    Jackeriss  
       2017-02-16 14:50:23 +08:00 via iPhone
    @ixiaozhi 神圣的 F2 连着我们的思想
    loveskyforever
        53
    loveskyforever  
       2017-02-16 14:54:50 +08:00
    用的是 SBDoc ,可以内网测试, mock 数据,自动生成文档,干净无插件 http://123.57.77.6
    Ypoem
        54
    Ypoem  
       2017-02-16 15:04:02 +08:00
    支持下
    yy1300326388
        55
    yy1300326388  
       2017-02-16 16:35:38 +08:00
    postmant
    zorui
        56
    zorui  
       2017-02-16 16:49:24 +08:00
    swagger +1
    zorui
        57
    zorui  
       2017-02-16 16:50:19 +08:00
    swagger + asciidoc
    v4ex4b
        58
    v4ex4b  
       2017-02-16 16:59:30 +08:00
    @SourceMan \(≧▽≦)/
    irory
        59
    irory  
       2017-02-16 17:59:50 +08:00
    推荐自动生成文档, 比如 PY 的 sphinx , api 更新方便维护 ,一键生成也方便。
    ivanyin
        60
    ivanyin  
       2017-02-16 18:44:07 +08:00
    用 RAP
    codeyung
        61
    codeyung  
       2017-02-16 19:04:04 +08:00
    Confluence
    freestyle
        62
    freestyle  
       2017-02-16 19:50:09 +08:00 via iPhone
    API 的话 Swagger 搭一个本地服务器 然后用 yaml 写文档就行了,自动渲染 高亮
    jimyan
        63
    jimyan  
    OP
       2017-02-16 20:28:01 +08:00
    @freestyle 这个只能是 java 吗
    lgn21st
        64
    lgn21st  
       2017-02-16 20:40:46 +08:00
    freestyle
        65
    freestyle  
       2017-02-16 20:52:58 +08:00
    @jimyan 任何语言 API 是 json 构建的就行 官网:http://swagger.io/swagger-ui/ github:https://github.com/swagger-api/swagger-ui clone 下来, 随便搞个简单 http 服务器, dist 目录作为作为 root 目录就可以跑起来 也可以后面小修改下加登录才能查看 语法规范在这里 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
    klgd
        66
    klgd  
       2017-02-16 21:16:20 +08:00
    @settings 嗯 是的 可以对比吗?
    Monstercat
        67
    Monstercat  
       2017-02-16 21:18:43 +08:00
    Github Private Repo 放 MD...
    lzjamao
        68
    lzjamao  
       2017-02-16 21:23:23 +08:00
    abirdcanfly
        69
    abirdcanfly  
       2017-02-16 22:42:01 +08:00
    我是业务部门的, 对接的 IT 部门每用一次 API 让我们在对接门户导一次 <<<吐槽
    langjiyuan
        70
    langjiyuan  
       2017-02-16 22:55:42 +08:00
    意念传输 2333
    IgniteWhite
        71
    IgniteWhite  
       2017-02-16 23:14:18 +08:00
    楼主附言的背后应该是一张面无表情的脸
    romennts
        72
    romennts  
       2017-02-17 00:32:35 +08:00
    @kancloud 我在用看云 Hhhh
    cxbig
        73
    cxbig  
       2017-02-17 02:00:55 +08:00
    公司用 Atlassian 的产品
    所以需求和设计文档一般都是 Confluence 做描述, PSD 类设计文件用 Google Drive 共享。
    关于 API 文档,如 PHP 项目:公司要求每个 attribute 和 method 必须写清楚 PHP Doc ,大家都用 PhpStorm ,一个类有什么东西、怎么用一目了然。
    msg7086
        74
    msg7086  
       2017-02-17 03:34:55 +08:00
    意念传输,这个总结得很好……
    whalegia
        75
    whalegia  
       2017-02-17 05:25:27 +08:00
    OneNote + Swagger
    rashawn
        76
    rashawn  
       2017-02-17 06:43:37 +08:00 via iPhone
    通过代码生成 缺点是代码里注释有点多…
    Cbdy
        77
    Cbdy  
       2017-02-17 07:43:51 +08:00 via Android
    根据代码注释生成文档( javadoc )+ 根据 api 接口使用 springfox 的工具生成 adoc

    只要写好代码,文档都是自动生成的
    winglight2016
        78
    winglight2016  
       2017-02-17 09:25:52 +08:00
    意念传输——就服这个,能传授吗?
    juice
        79
    juice  
       2017-02-17 09:29:46 +08:00
    postman , swagger
    Yuansir
        80
    Yuansir  
       2017-02-17 09:30:06 +08:00
    居然没有 gitbook
    zhangliang605
        81
    zhangliang605  
       2017-02-17 09:54:55 +08:00
    Confluence 。
    是我们是一个 1200+人的团队,面临开发,测试,产品经理,项目经理,运营,商务等等各个部门的协作。 Confluence 能跟公司的通信录系统,邮箱系统对接。当关注的文档发生变化时,立即发送邮件给相关同事。同时, Confluence 支持各种插件,富文本编辑,代码高亮,评论,备注等等功能一应俱全。
    antowa
        82
    antowa  
       2017-02-17 10:20:02 +08:00
    我司使用意念传输。精神授权。
    settings
        83
    settings  
       2017-02-17 11:42:09 +08:00
    @klgd 默认不支持,可以反射 markdown ,我们是用 swagger api 反射 markdown ,再把 markdown 提交 git ,通过 gollum 展示 wiki 。

    生成 markdown 的脚本: https://github.com/ZhangBohan/swagger_to_markdown
    keepcleargas
        84
    keepcleargas  
       2017-02-17 11:45:38 +08:00
    slate + git
    wjh3936
        85
    wjh3936  
       2017-02-17 12:31:09 +08:00
    文档?看代码 [冷漠脸]
    sumuu
        86
    sumuu  
       2017-02-17 12:59:47 +08:00
    Swagger + Google Drive
    klgd
        87
    klgd  
       2017-02-17 13:34:23 +08:00
    @settings 呃~
    要这么麻烦哦
    billyu
        88
    billyu  
       2017-02-17 13:35:58 +08:00
    我用的 EasyAPI
    caotian
        89
    caotian  
       2017-02-17 15:36:32 +08:00
    settings
        90
    settings  
       2017-02-17 16:35:52 +08:00
    @klgd 恩,是的 :D
    Hypn0s
        91
    Hypn0s  
       2017-02-17 17:14:04 +08:00
    Confluence+1
    flowerwrong
        92
    flowerwrong  
       2017-02-17 17:15:10 +08:00 via iPhone
    口口想传
    sampeng
        93
    sampeng  
       2017-02-17 19:48:17 +08:00
    api 是什么东西?可以吃吗?
    airingursb
        94
    airingursb  
       2017-02-19 14:01:53 +08:00 via iPhone
    rap
    962680038
        95
    962680038  
       2017-02-20 10:00:42 +08:00
    SBDoc 不错啊,楼主可以去了解下,操作很简洁,效果很好,链接: http://123.57.77.6/
    dozer47528
        96
    dozer47528  
       2017-02-20 10:48:44 +08:00
    想不收费自己搭建的话,可以使用 https://apiblueprint.org/
    它本身提供云服务,但也可以自己搭建。写文档就是写 markdown , github 也认这种格式。





    然后开源社区已经做好了各种工具,包括把 apiblueprint 格式生成 html , apiblueprint 生成 mock server 等等,非常方便。
    我做了个 docker 镜像,只要提供你们写文档的 git 仓库,就可以一键搭建。包含文档服务器, mock server 和 hook api (文档更新的时候自动更新相关内容)
    https://github.com/dozer47528/api-blueprint-docker

    另外,你可能会需要对静态网站做 oauth2 认证功能,可以利用这个东西: https://github.com/bitly/oauth2_proxy

    可以配置邮箱白名单,这样只有你们公司的人能访问了。
    HowToMakeLove
        97
    HowToMakeLove  
       2017-02-20 21:43:04 +08:00
    apidoc
    jsq2627
        98
    jsq2627  
       2017-03-09 13:04:34 +08:00
    个人觉得从测试用例生成文档是体验最棒的文档开发方式。

    最近给 node.js 做的轮子,强力推荐一下
    https://github.com/stackia/test2doc.js
    yuhanle
        99
    yuhanle  
       2017-03-21 14:11:19 +08:00
    先开大会,再开小会,最后一对一,手把手同步需求
    HuntBao
        100
    HuntBao  
       2017-09-28 11:48:20 +08:00
    可以试试 NEI 接口管理平台: https://nei.netease.com
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1037 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 32ms · UTC 22:29 · PVG 06:29 · LAX 15:29 · JFK 18:29
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.