Home Sign Up Sign In
• 请不要在回答技术问题时复制粘贴 AI 生成的内容
ansheng
V2EX  ›  程序员

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

  •   
  •   ansheng ·
    anshengme · Apr 13, 2017 · 9689 views
    This topic created in 3493 days ago, the information mentioned may be changed or developed.

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

    哎。 Fuck

    Supplement 1  ·  Apr 14, 2017

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

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

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

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

    心有灵犀
    xxdd
    xxdd
    Apr 13, 2017
    47
    口口相传

    心有灵犀

    (●'◡'●)ﾉ♥
    prasanta
    prasanta
    Apr 13, 2017
    48
    用 mkdocs+git
    Ouyangan
    Ouyangan
    Apr 13, 2017
    49
    swagger+1
    qdpoboy
    qdpoboy
    Apr 13, 2017
    50
    喊！呀
    Wilon
    Wilon
    Apr 13, 2017
    51
    @izoabr 上班着，要被你的答案笑死了，虽然我们也是口口相传
    ij666
    ij666
    Apr 13, 2017
    52
    看来不止我们用 word /(ㄒoㄒ)/~~
    kisnows
    kisnows
    Apr 13, 2017
    53
    Word Wiki 有道云 + 口口相传
    nextbox
    nextbox
    Apr 13, 2017
    54
    RAP
    ydq419453527
    ydq419453527
    Apr 13, 2017
    56
    @zi @strongcoder @Vvfan txt 的默默路过 =。=
    Blazings
    Blazings
    Apr 13, 2017 via Android
    57
    口口相传牛逼
    auhah
    auhah
    Apr 13, 2017
    58
    想起了前前前公司，我刚工作的时候

    CTO 特别屌

    自己撸了一套 API 网站

    还以为是 IT 公司标配

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