V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
yibin001
V2EX  ›  问与答

大家都用什么写 api 文档?

  •  
  •   yibin001 · 2014-09-19 10:36:17 +08:00 · 6828 次点击
    这是一个创建于 3479 天前的主题,其中的信息可能已经有所发展或是发生改变。
    列出所有api,每个api需要的参数列表、参数类型、是否必填、参数说明。
    每个api的返回值。
    21 条回复    2014-09-20 16:06:09 +08:00
    lizhijun
        1
    lizhijun  
       2014-09-19 10:39:17 +08:00
    markdown?
    yibin001
        2
    yibin001  
    OP
       2014-09-19 10:44:14 +08:00
    @lizhijun
    但是要用表格来写参数列表,比较头疼。。
    linnchord
        3
    linnchord  
       2014-09-19 10:44:18 +08:00
    wiki by markdown
    cnxh
        4
    cnxh  
       2014-09-19 10:49:16 +08:00
    haroopad
    tolbkni
        5
    tolbkni  
       2014-09-19 10:59:47 +08:00   ❤️ 1
    @yibin001 Markdown + GFM
    jamiesun
        6
    jamiesun  
       2014-09-19 11:02:19 +08:00
    不用sphinx吗
    lululau
        7
    lululau  
       2014-09-19 11:06:55 +08:00
    TangMonk
        8
    TangMonk  
       2014-09-19 11:10:03 +08:00
    bitbucket 的 wiki
    FuryBean
        9
    FuryBean  
       2014-09-19 11:11:30 +08:00
    YuiDoc应该满足楼主的需求。YuiDoc实际上是不限制语言的,而且也不需要写到源码里面。
    TangMonk
        10
    TangMonk  
       2014-09-19 11:12:11 +08:00
    上次做的一个外包, 大家瞟下文档, 有没得啥子可提高的:

    https://bitbucket.org/wuao/daxuebao-api/wiki/Home
    davepkxxx
        11
    davepkxxx  
       2014-09-19 11:12:25 +08:00
    javadoc
    yibin001
        12
    yibin001  
    OP
       2014-09-19 11:29:57 +08:00
    @lululau
    这个不错。
    yibin001
        13
    yibin001  
    OP
       2014-09-19 11:32:38 +08:00
    @lululau 语法也挺蛋疼的。。
    lincanbin
        14
    lincanbin  
       2014-09-19 11:56:27 +08:00
    markdown
    konakona
        15
    konakona  
       2014-09-19 12:23:46 +08:00
    哎...只能用excel、word写,用wiki除了我以外没人愿意维护,因为不愿意学wiki的写法...TAT
    shiny
        16
    shiny  
       2014-09-19 12:25:03 +08:00
    javadoc / phpdoc 这类语法,自动导出下就行了.
    hehuozhao
        17
    hehuozhao  
       2014-09-19 12:35:32 +08:00
    zeayes
        18
    zeayes  
       2014-09-19 12:49:49 +08:00
    trac wiki
    Winny
        19
    Winny  
       2014-09-19 16:59:25 +08:00 via iPad
    ASP.Net的Web api框架自动生成
    xylophone21
        20
    xylophone21  
       2014-09-19 20:42:42 +08:00
    这个要看语言吧,
    c用doxygen
    java用javadoc
    JS只用NP API做过扩展,没找到太好的方案,现在感觉自定义注释+脚本+latex不错,不过没实施过。

    总之,个人的感觉是接口文档不写在代码里就等于没写,根本没人看,同步也非常麻烦。

    猿类都懒
    pantaovay
        21
    pantaovay  
       2014-09-20 16:06:09 +08:00
    markdown 使用 api blueprint生成 很酷炫
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   2684 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 44ms · UTC 15:30 · PVG 23:30 · LAX 08:30 · JFK 11:30
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.