Web 后台文档怎么写?或者有什么快速生成的框架? - V2EX
V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
请不要在回答技术问题时复制粘贴 AI 生成的内容
int64ago
V2EX    程序员

Web 后台文档怎么写?或者有什么快速生成的框架?

  •  1
     
  •   int64ago
    int64ago 2016-03-15 21:12:45 +08:00 4286 次点击
    这是一个创建于 3506 天前的主题,其中的信息可能已经有所发展或是发生改变。

    之前写过一个后台文档,感觉很随意,很想把文档这个事正规起来,不知道有什么适合 NodeJS Web 后台写文档的架子 /平台 /方法 /...

    当然,最终优先考虑 Markdown 格式,其它方便的话也可以

    补充:文档主题是网络 API 描述 /参数 /例子 /...

    18 条回复    2016-03-16 15:12:29 +08:00
    int64ago
        1
    int64ago  
    OP
       2016-03-15 21:13:24 +08:00
    比较急,所以无奈自顶
    BiggerLonger
        2
    BiggerLonger  
       2016-03-15 21:27:05 +08:00   1
    Sphinx
    angelface
        3
    angelface  
       2016-03-15 21:34:13 +08:00   1
    哟, 我前几天正琢磨要不要根据接品返回的 json 生成一个模板,然后自己填注释,今天就看到有这样的需求。虽然不太一样,但有点类似,我的想法是用 markdown,大根是这个样子:
    ### 通讯录
    - [通讯列表](#contacts)

    <a name="contacts" />
    ### 通讯录
    家长
    http://10.0.0.1:3000/contacts [GET]

    返回

    title:string //title


    不过感觉看起来也不是特别直观。
    int64ago
        4
    int64ago  
    OP
       2016-03-15 21:36:33 +08:00
    @angelface 确实不是很直观

    刚刚 Google 了一圈,看到 http://tripit.github.io/slate/?python#introduction 挺符合我要求的,正在看他们项目的 README.md ,如果这里看不到更好的方案我就用这个了
    feiyuanqiu
        5
    feiyuanqiu  
       2016-03-15 22:20:35 +08:00 via iPhone   1
    我之前弄了一个,通过解析接口的 validator 规则生成入参的 docblock ,解析接口的 docblock 生成文档 api 参数,模拟登陆我们的文档系统,把生成的文档 post 上去,授权...工作流程就是写完接口原型,然后执行下这个工具就把接口文档弄好了…看起来挺美好,但同事们开发环境不统一,用不了工具,最后就变成谁写完接口就喊我给他加文档,简直烦躁

    最近接口文档管理换成 rap 了,要准备适配它的接口格式,用了一下,真是难用,说是秒存,竟然是把所有文档数据一起往服务器传,一个巨大的 json 字符串…多人编辑同一个文档的时候用乐观锁,一直到编辑完保存的时候才告诉你也有其他人在编辑这个,你不能保存,然后就一直报异常,所有人都编辑不了了,开始我还以为是公司里谁闭门造车搞出来的呢,结果一搜好像还是阿里开发的...
    ryanking8215
        6
    ryanking8215  
       2016-03-15 22:26:43 +08:00   2
    mkdocs , upyun 用它来生成 api 文档页面。
    angelface
        7
    angelface  
       2016-03-15 23:38:41 +08:00
    @ryanking8215 这个不错, 有了 table 可以做不少事儿。
    denghongcai
        8
    denghongcai  
       2016-03-15 23:59:28 +08:00   1
    dphdjy
        9
    dphdjy  
       2016-03-16 01:02:49 +08:00 via Android   1
    写个 yaml/swagger 的标准接口~剩下随便找工具生成就好了
    hpu423
        10
    hpu423  
       2016-03-16 09:26:48 +08:00   1
    janxin
        11
    janxin  
       2016-03-16 11:19:03 +08:00
    @denghongcai swagger 除了写起来很烦其他都挺好
    Lucups
        12
    Lucups  
       2016-03-16 11:20:43 +08:00
    @denghongcai +1
    @janxin 支持 yaml 写了,不过还是比较嗦。。。
    @dphdjy 不错
    denghongcai
        13
    denghongcai  
       2016-03-16 11:28:17 +08:00
    @janxin 直接写在注释里面,顺手就写了

    web ui 太丑陋,得自己改改
    mozutaba
        14
    mozutaba  
       2016-03-16 11:54:44 +08:00
    @denghongcai +1 , Google , IBM 都用的。
    DoLinux
        15
    DoLinux  
       2016-03-16 13:39:28 +08:00
    帮顶。
    是 ccj 吗
    sherwinkoo
        16
    sherwinkoo  
       2016-03-16 14:10:37 +08:00   1
    apiDoc ,这个工具本身就是用 nodejs 写的,我们公司现在在用,简单方便,试试看。链接: http://apidocjs.com/
    ldw4033
        17
    ldw4033  
       2016-03-16 14:23:24 +08:00   1
    RAML
    Hayesz
        18
    Hayesz  
       2016-03-16 15:12:29 +08:00   1
    推荐 swaggerui
    关于     帮助文档     自助推广系统     博客     API     FAQ     Solana     1645 人在线   最高记录 6679       Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 29ms UTC 16:23 PVG 00:23 LAX 09:23 JFK 12:23
    Do have faith in what you're doing.
    ubao msn 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