各位服务端程序员一般用什么工具写 api 文档给客户端看? - V2EX
V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
georgetso
V2EX    问与答

各位服务端程序员一般用什么工具写 api 文档给客户端看?

  •  
  •   georgetso 2016-05-03 01:08:24 +08:00 6367 次点击
    这是一个创建于 3450 天前的主题,其中的信息可能已经有所发展或是发生改变。
    我目前拿到的 api 文档大部分都是 word
    21 条回复    2016-05-10 10:06:18 +08:00
    silencewwt
        1
    silencewwt  
       2016-05-03 01:18:15 +08:00
    Sphinx, 然后生成 `read the docs` 风格的 html
    ewBuyVmLZMZE
        2
    ewBuyVmLZMZE  
       2016-05-03 01:44:34 +08:00
    是时候安利 swagger 了
    Victor215
        3
    Victor215  
       2016-05-03 07:55:53 +08:00 via Android
    我们用 markdown
    crysislinux
        4
    crysislinux  
       2016-05-03 08:33:10 +08:00
    raml , execl 也比 word 要好吧,其实我觉得 execl 也还可以。。。
    lecher
        5
    lecher  
       2016-05-03 08:48:57 +08:00 via Android
    偷懒的时候直接写个接口专门扫文件,然后输出注释就显示,这样给前端一个 Web 接口就可以看所有注释了。
    好处是只需要维护一份文档,方便实时更新,把注释写好就行,坏处太多列不完,文档不规范,没有格式等等一堆工程化要求没有达到
    yellowV2ex
        6
    yellowV2ex  
       2016-05-03 09:01:33 +08:00   5
    我最近用了一个牛逼的东西,然后报价可以多报个一两千,这就是逼格的价值。

    用 aglio 生成文档 https://github.com/danielgtaylor/aglio ,原始格式是基于 markdown 的 API Blueprint https://apiblueprint.org/

    生出来的东西大概是这样子的: http://htmlpreview.github.io/?https://raw.githubusercontent.com/danielgtaylor/aglio/blob/master/examples/default.html
    以及三列版 http://htmlpreview.github.io/?https://raw.githubusercontent.com/danielgtaylor/aglio/blob/master/examples/default-triple.html
    pepsin
        7
    pepsin  
       2016-05-03 09:32:12 +08:00
    Paw 改改 JS 生成的也不错
    odirus
        8
    odirus  
       2016-05-03 09:35:54 +08:00
    表示强烈关注
    fwrq41251
        9
    fwrq41251  
       2016-05-03 09:46:28 +08:00   1
    推荐 miredot,个人觉得比 swaggeer 好用。
    chinajik
        10
    chinajik  
       2016-05-03 09:49:11 +08:00
    @fwrq41251 要付费~ 然而感觉不错~~
    chinajik
        11
    chinajik  
       2016-05-03 09:50:15 +08:00
    @fwrq41251
    :)

    Always free for non-commercial open source projects.
    gucheen
        12
    gucheen  
       2016-05-03 09:56:41 +08:00
    swagger 和 markdown 搭配
    Drifter
        13
    Drifter  
       2016-05-03 10:02:34 +08:00   1
    1 ,做过接口扫描+接口注释输出。

    优点是只用维护一份文档;
    缺点是页面比较简单,不好定制;

    2 ,现在使用的 pelican+某个主题
    优点是生成快,不用管文档结构,只写文档;
    缺点是主题不好找,不好作内部链接引用。

    想尝试用 sphinx+read the doc ,但是 rst 的复杂写法让我望而却步了。
    tadtung
        14
    tadtung  
       2016-05-03 11:36:49 +08:00
    gitbook 好些吧,,虽然之前我自己也写过,,,不过还是多用 gitbook
    roys
        15
    roys  
       2016-05-03 11:41:10 +08:00
    swagger + 1
    rainysia
        16
    rainysia  
       2016-05-03 12:01:03 +08:00
    swagger + 1
    ferstar
        17
    ferstar  
       2016-05-03 15:03:23 +08:00
    mark 下, 表示准备用 swagger
    kenshinhu
        18
    kenshinhu  
       2016-05-03 15:11:39 +08:00
    因为主要用 node,所以用 apidoc 来生成文档
    cookit
        19
    cookit  
       2016-05-03 15:49:22 +08:00
    confluence wiki
    Oceanz
        20
    Oceanz  
       2016-05-03 17:07:42 +08:00
    https://github.com/thx/RAP 感觉还可以。
    hjxx
        21
    hjxx  
       2016-05-10 10:06:18 +08:00
    swagger 自动生成了
    关于     帮助文档     自助推广系统     博客     API     FAQ     Solana     5888 人在线   最高记录 6679       Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 34ms UTC 03:20 PVG 11:20 LAX 20:20 JFK 23:20
    Do have faith in what you're doing.
    ubao snddm index pchome yahoo rakuten mypaper meadowduck bidyahoo youbao zxmzxm asda bnvcg cvbfg dfscv mmhjk xxddc yybgb zznbn ccubao uaitu acv GXCV ET GDG YH FG BCVB FJFH CBRE CBC GDG ET54 WRWR RWER WREW WRWER RWER SDG EW SF DSFSF fbbs ubao fhd dfg ewr dg df ewwr ewwr et ruyut utut dfg fgd gdfgt etg dfgt dfgd ert4 gd fgg wr 235 wer3 we vsdf sdf gdf ert xcv sdf rwer hfd dfg cvb rwf afb dfh jgh bmn lgh rty gfds cxv xcv xcs vdas fdf fgd cv sdf tert sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf sdf shasha9178 shasha9178 shasha9178 shasha9178 shasha9178 liflif2 liflif2 liflif2 liflif2 liflif2 liblib3 liblib3 liblib3 liblib3 liblib3 zhazha444 zhazha444 zhazha444 zhazha444 zhazha444 dende5 dende denden denden2 denden21 fenfen9 fenf619 fen619 fenfe9 fe619 sdf sdf sdf sdf sdf zhazh90 zhazh0 zhaa50 zha90 zh590 zho zhoz zhozh zhozho zhozho2 lislis lls95 lili95 lils5 liss9 sdf0ty987 sdft876 sdft9876 sdf09876 sd0t9876 sdf0ty98 sdf0976 sdf0ty986 sdf0ty96 sdf0t76 sdf0876 df0ty98 sf0t876 sd0ty76 sdy76 sdf76 sdf0t76 sdf0ty9 sdf0ty98 sdf0ty987 sdf0ty98 sdf6676 sdf876 sd876 sd876 sdf6 sdf6 sdf9876 sdf0t sdf06 sdf0ty9776 sdf0ty9776 sdf0ty76 sdf8876 sdf0t sd6 sdf06 s688876 sd688 sdf86