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

话说你司的 API 文档是如何进行管理的?

  •  
  •   ansheng ·
    anshengme · 2017-04-13 10:19:07 +08:00 · 7885 次点击
    这是一个创建于 2780 天前的主题,其中的信息可能已经有所发展或是发生改变。

    遇到一个尴尬的问题,我司 API 文档都是使用 markdown 来写的,然而是放在项目目录下面的 README.md 中,但是多人人多的时候修改起来就比较麻烦,就想用有没有一种在线的 API 文档管理程序撒的,石墨固然好,好像不支持 Markdown 所以没打算用。

    哎。 Fuck

    第 1 条附言  ·  2017-04-14 09:54:36 +08:00

    看了各位的评论,表示API文档还是可以独立部署代表比较好,我可不想把自己程序的API说明丢在别人家。

    其次,看了下swagger,感觉UI挺不错,抽时间研究下。

    我司下载就是放在仓库下面的README.md中。

    98 条回复    2020-09-04 14:20:56 +08:00
    xuanyan
        1
    xuanyan  
       2017-04-13 10:30:53 +08:00
    我们用的 mediawiki 搭建的 api 接口词条
    lawmil
        2
    lawmil  
       2017-04-13 10:39:17 +08:00   ❤️ 1
    既然是 md 写的,推荐个系统 docsify 很方便,样式默认 vue 也可以改其他
    ansheng
        3
    ansheng  
    OP
       2017-04-13 10:39:24 +08:00
    @xuanyan 可以在线修改吗?我想着尽可能就放内网,
    ansheng
        4
    ansheng  
    OP
       2017-04-13 10:41:05 +08:00
    @lawmil 这个确实很不错,可以考虑。
    hekunhotmail
        5
    hekunhotmail  
       2017-04-13 10:43:05 +08:00
    wiki 不谢
    zi
        6
    zi  
       2017-04-13 10:46:58 +08:00
    我司用 word 。。真的要哭出声来
    AlisaDestiny
        7
    AlisaDestiny  
       2017-04-13 10:52:58 +08:00
    ansheng
        8
    ansheng  
    OP
       2017-04-13 10:53:54 +08:00
    @zi 心疼你三秒。
    ansheng
        9
    ansheng  
    OP
       2017-04-13 10:54:35 +08:00
    @AlisaDestiny 贵了点,哈哈。
    domty
        10
    domty  
       2017-04-13 11:13:29 +08:00
    confluence
    tpsxiong
        11
    tpsxiong  
       2017-04-13 11:15:41 +08:00
    linoder
        12
    linoder  
       2017-04-13 12:24:46 +08:00
    swagger
    flyingghost
        13
    flyingghost  
       2017-04-13 12:35:43 +08:00
    www.xiaoyaoji.com
    可内网部署
    h4x3rotab
        14
    h4x3rotab  
       2017-04-13 12:47:55 +08:00
    Google 是和源码目录放在一起的 md 文件,同样加入版本管理,代码审查。然后再搭配一个搜索。
    lusyoe
        15
    lusyoe  
       2017-04-13 13:08:45 +08:00 via iPhone
    swagger +1
    crossoverJie
        16
    crossoverJie  
       2017-04-13 13:22:00 +08:00
    有 doc 和 wiki
    tkisme
        17
    tkisme  
       2017-04-13 13:22:46 +08:00
    swagger +1
    nashxk
        18
    nashxk  
       2017-04-13 13:36:07 +08:00
    confluence 。不过没用 markdown ,而且改版的时候更新也不是很及时。。
    ansheng
        19
    ansheng  
    OP
       2017-04-13 14:08:13 +08:00
    @flyingghost 表示打不开,就是需要内网部署的。
    ansheng
        20
    ansheng  
    OP
       2017-04-13 14:08:28 +08:00
    @nashxk 没 markdown 真的很痛苦
    ansheng
        21
    ansheng  
    OP
       2017-04-13 14:08:50 +08:00
    @tkisme2013
    @lusyoe
    @linoder
    考虑下午玩玩看。
    kooze
        22
    kooze  
       2017-04-13 14:10:41 +08:00   ❤️ 4
    口耳相传
    zhuf
        23
    zhuf  
       2017-04-13 14:11:36 +08:00
    apidoc
    ansheng
        24
    ansheng  
    OP
       2017-04-13 14:15:45 +08:00
    @kooze 这个吊
    snriud
        25
    snriud  
       2017-04-13 14:36:41 +08:00
    最开始是写在 wiki 里,认认真真,完完整整,慢慢地就不维护了,有人要接口文档的话就用 postman 请求一次,截图发给谁。。。
    ansheng
        26
    ansheng  
    OP
       2017-04-13 14:39:09 +08:00
    @snriud 我也在用 postman ,因为老大没买这个东,所以还不能做到团队公用,
    wudanyang
        27
    wudanyang  
       2017-04-13 14:51:00 +08:00
    wiki, 不会调格式
    gengqiupeng
        28
    gengqiupeng  
       2017-04-13 14:54:18 +08:00
    小幺鸡在线文档。不过不是用 markdown 写的
    kaka8wp
        29
    kaka8wp  
       2017-04-13 15:06:39 +08:00
    有部分文档但基本上不是最新的,最新的也是靠口耳相传
    ivvei
        30
    ivvei  
       2017-04-13 15:12:31 +08:00
    没有文档。自己翻代码
    izoabr
        31
    izoabr  
       2017-04-13 15:18:04 +08:00
    口口相传
    huigeer
        32
    huigeer  
       2017-04-13 15:24:25 +08:00
    apidoc + 1
    ArthurKing
        33
    ArthurKing  
       2017-04-13 15:26:06 +08:00
    swagger +1
    huigeer
        34
    huigeer  
       2017-04-13 15:27:06 +08:00
    更正: ShowDoc
    qiu0130
        35
    qiu0130  
       2017-04-13 15:38:56 +08:00 via Android
    难道没有用 tower 的?
    klgd
        36
    klgd  
       2017-04-13 15:45:12 +08:00
    showdoc + apidoc
    showdoc 是前人用的, coding+编辑维护不是方便,后来用 apidoc ,注释直接写在 code 里,然后命令生成,虽然注释在编写时也不是太方便,但感觉对 coding 和维护好一点儿
    orderc
        37
    orderc  
       2017-04-13 16:08:00 +08:00
    gitbook
    ansheng
        38
    ansheng  
    OP
       2017-04-13 16:14:40 +08:00
    @klgd View 里面加注释确实会给后人一个更方便理解,但我司的风格不适合
    ansheng
        39
    ansheng  
    OP
       2017-04-13 16:15:01 +08:00
    @qiu0130 我司就用,哈哈。
    freezhan
        40
    freezhan  
       2017-04-13 16:19:46 +08:00
    swagger+1
    strongcoder
        41
    strongcoder  
       2017-04-13 16:30:46 +08:00
    我司用 word 。。快被气死
    Observer42
        42
    Observer42  
       2017-04-13 16:38:03 +08:00
    swagger
    zoffy
        43
    zoffy  
       2017-04-13 16:39:54 +08:00
    @snriud #25 是这样的
    subdued
        44
    subdued  
       2017-04-13 16:42:07 +08:00   ❤️ 4
    我司 API 文档靠口口相传
    guodont
        45
    guodont  
       2017-04-13 16:46:31 +08:00
    swagger +1
    apidoc +1
    virusdefender
        46
    virusdefender  
       2017-04-13 16:50:57 +08:00   ❤️ 1
    口口相传

    心有灵犀
    xxdd
        47
    xxdd  
       2017-04-13 16:56:46 +08:00
    口口相传

    心有灵犀

    (●'◡'●)ノ♥
    prasanta
        48
    prasanta  
       2017-04-13 17:02:46 +08:00
    用 mkdocs+git
    Ouyangan
        49
    Ouyangan  
       2017-04-13 17:17:10 +08:00
    swagger+1
    qdpoboy
        50
    qdpoboy  
       2017-04-13 17:36:00 +08:00
    喊!呀
    Wilon
        51
    Wilon  
       2017-04-13 17:36:47 +08:00
    @izoabr 上班着,要被你的答案笑死了,虽然我们也是口口相传
    Vvfan
        52
    Vvfan  
       2017-04-13 17:37:11 +08:00
    看来不止我们用 word /(ㄒoㄒ)/~~
    kisnows
        53
    kisnows  
       2017-04-13 17:54:17 +08:00
    Word Wiki 有道云 + 口口相传
    nextbox
        54
    nextbox  
       2017-04-13 17:56:12 +08:00
    RAP
    imherer
        55
    imherer  
       2017-04-13 18:22:43 +08:00
    ydq419453527
        56
    ydq419453527  
       2017-04-13 18:29:33 +08:00
    @zi @strongcoder @Vvfan txt 的默默路过 =。=
    Blazings
        57
    Blazings  
       2017-04-13 18:30:13 +08:00 via Android
    口口相传牛逼
    auhah
        58
    auhah  
       2017-04-13 18:31:49 +08:00
    想起了前前前公司,我刚工作的时候

    CTO 特别屌

    自己撸了一套 API 网站

    还以为是 IT 公司标配

    后来几个公司 tmd 全是 word
    mfu
        59
    mfu  
       2017-04-13 18:32:03 +08:00
    写 WORD 里扔 SVN 上。 T_T
    WhoMercy
        60
    WhoMercy  
       2017-04-13 18:43:24 +08:00 via Android
    遇到过 word 生成 html 扔内网服务器,给个固定网址的……
    nameldk
        61
    nameldk  
       2017-04-13 19:53:28 +08:00
    文档是写在代码里,然后有专门处理程序会把代码的文档提取出来,生成 api 文档,同时生成测试工具:)
    a412739861
        62
    a412739861  
       2017-04-13 20:04:35 +08:00
    @kooze #22 还不错了,我们是代码讲那过去的故事……
    zhleonix
        63
    zhleonix  
       2017-04-13 20:09:19 +08:00
    用 Swagger 或者 RAML 写 YAML 规范,自动产生文档和代码。
    xieweizhi007
        64
    xieweizhi007  
       2017-04-13 21:53:05 +08:00 via iPhone
    apiary
    xieweizhi007
        65
    xieweizhi007  
       2017-04-13 21:53:37 +08:00 via iPhone
    更正: apiary
    G900
        66
    G900  
       2017-04-13 22:02:52 +08:00
    GitLab ,和代码分开,做一个单独的 doc 库,用 markdown 写,管理方便
    V2exUser
        67
    V2exUser  
       2017-04-13 22:07:01 +08:00
    @subdued 听过口耳相传,实在想不出贵司的口口相传是怎样的风景。
    orvice
        68
    orvice  
       2017-04-13 22:50:07 +08:00
    swagger :)
    xu1ming
        69
    xu1ming  
       2017-04-13 22:53:11 +08:00 via iPhone   ❤️ 1
    我司 google doc
    mingyun
        70
    mingyun  
       2017-04-13 23:10:52 +08:00
    dokuwiki
    loveuqian
        71
    loveuqian  
       2017-04-13 23:36:45 +08:00 via iPhone
    就一条 curl 命令
    Jakesoft
        72
    Jakesoft  
       2017-04-14 00:50:49 +08:00
    竟然没有 sphinx ,专业文档编写 100 年
    zzyzxd
        73
    zzyzxd  
       2017-04-14 07:44:49 +08:00
    前公司是把 git 目录 mount 到一个 MkDocs 的 container 里……
    jwangkun
        74
    jwangkun  
       2017-04-14 07:46:05 +08:00 via Android
    没人推荐小幺鸡么?
    yalanaika
        75
    yalanaika  
       2017-04-14 08:03:36 +08:00
    html - chm
    libook
        76
    libook  
       2017-04-14 08:06:07 +08:00
    个人觉得 API 文档维护的最大问题是忘记维护,或者有时候赶时间就懒得维护,所以个人倾向于将 API 文档与代码放在一起。
    我们是 JS 全栈, JS 有一套 JSDoc 标准,适用于非 API 场景的文档编写,依照这个标准,有一个 APIDoc 工具,可以用类似 JSDoc 的方式在代码中用注释编写 API 文档,但是在实际应用过程中感觉不适合我们的应用场景,所以自己写了一个 URIDoc https://www.npmjs.com/package/uridoc
    目前还是 v1 的初级阶段,欢迎 Fork 和 PullRequest
    eurry
        77
    eurry  
       2017-04-14 08:33:39 +08:00
    hareandlion
        78
    hareandlion  
       2017-04-14 08:34:50 +08:00 via iPhone
    口口相传 +1
    tangbl93
        79
    tangbl93  
       2017-04-14 08:41:36 +08:00
    word + 1
    billion
        80
    billion  
       2017-04-14 08:44:06 +08:00
    @WhoMercy 我前公司就是这样的。
    yellowV2ex
        81
    yellowV2ex  
       2017-04-14 08:47:46 +08:00
    腾讯微信的公众号开发文档就是 word ,最开始的时候,里面引号还是中文的。
    yellowV2ex
        82
    yellowV2ex  
       2017-04-14 08:48:32 +08:00
    loading
        83
    loading  
       2017-04-14 08:50:36 +08:00
    自己看代码
    zongren
        84
    zongren  
       2017-04-14 08:54:21 +08:00   ❤️ 1
    QQ 聊天记录
    zcwlwen
        85
    zcwlwen  
       2017-04-14 09:16:26 +08:00
    写 markdown 扔在 gitlab 上
    BearD01001
        86
    BearD01001  
       2017-04-14 09:35:43 +08:00
    额,公司的 boss 系统有 API 文档检索功能,虽然界面粗糙,不过挺实用
    HuntBao
        87
    HuntBao  
       2017-04-14 09:39:57 +08:00   ❤️ 1
    我司自己开发的接口管理系统: https://nei.netease.com/
    silenceeeee
        88
    silenceeeee  
       2017-04-14 09:42:03 +08:00
    写 word 扔 svn ,己准备离职!
    stackboom
        89
    stackboom  
       2017-04-14 09:43:29 +08:00
    之前 swagger ,现在 RAP
    ansheng
        90
    ansheng  
    OP
       2017-04-14 09:55:23 +08:00
    @HuntBao 活捉大神一枚。
    Raidal
        91
    Raidal  
       2017-04-14 09:56:46 +08:00
    在用 [aglio]( https://github.com/danielgtaylor/aglio) ,不过数据多了后会有一点点慢。
    roricon
        92
    roricon  
       2017-04-14 10:33:37 +08:00
    sphinx 为啥没人提起呢.
    chipmuck
        93
    chipmuck  
       2017-04-14 10:39:43 +08:00
    https://www.v2ex.com/t/340795 难怪看的眼熟。。。。
    heaunter
        94
    heaunter  
       2017-04-14 10:43:44 +08:00 via Android
    必须小幺鸡啊……团队已从 RAP 切换到小幺鸡了
    Vvfan
        95
    Vvfan  
       2017-04-14 11:20:08 +08:00
    @zongren 你赢了
    magiclobster
        96
    magiclobster  
       2017-04-14 15:49:19 +08:00
    为什么不用 oschina 啊..
    changs1986
        97
    changs1986  
       2017-04-14 18:58:03 +08:00
    apidoc
    andychen1
        98
    andychen1  
       2020-09-04 14:20:56 +08:00
    api-mom.com 我司用这个
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   5466 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 103ms · UTC 03:27 · PVG 11:27 · LAX 19:27 · JFK 22:27
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.