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

[int64ago]

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

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

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

[int64ago]

比较急，所以无奈自顶

[BiggerLonger]

Sphinx

[angelface]

哟， 我前几天正琢磨要不要根据接品返回的 json 生成一个模板，然后自己填注释，今天就看到有这样的需求。虽然不太一样，但有点类似，我的想法是用 markdown,大根是这个样子：
### 通讯录
- [通讯列表](#contacts)

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

返回

title:string //title


不过感觉看起来也不是特别直观。

[int64ago]

@angelface 确实不是很直观

刚刚 Google 了一圈，看到 http://tripit.github.io/slate/?python#introduction 挺符合我要求的，正在看他们项目的 README.md ，如果这里看不到更好的方案我就用这个了

[feiyuanqiu]

我之前弄了一个，通过解析接口的 validator 规则生成入参的 docblock ，解析接口的 docblock 生成文档 api 参数，模拟登陆我们的文档系统，把生成的文档 post 上去，授权...工作流程就是写完接口原型，然后执行下这个工具就把接口文档弄好了…看起来挺美好，但同事们开发环境不统一，用不了工具，最后就变成谁写完接口就喊我给他加文档，简直烦躁

最近接口文档管理换成 rap 了，要准备适配它的接口格式，用了一下，真是难用，说是秒存，竟然是把所有文档数据一起往服务器传，一个巨大的 json 字符串…多人编辑同一个文档的时候用乐观锁，一直到编辑完保存的时候才告诉你也有其他人在编辑这个，你不能保存，然后就一直报异常，所有人都编辑不了了，开始我还以为是公司里谁闭门造车搞出来的呢，结果一搜好像还是阿里开发的...

[ryanking8215]

mkdocs ， upyun 用它来生成 api 文档页面。

[angelface]

@ryanking8215 这个不错， 有了 table 可以做不少事儿。

[denghongcai]

http://swagger.io/

[dphdjy]

写个 yaml/swagger 的标准接口~剩下随便找工具生成就好了

[hpu423]

看下这个

https://github.com/hpuwang/nndoc

[janxin]

@denghongcai swagger 除了写起来很烦其他都挺好

[Lucups]

@denghongcai +1
@janxin 支持 yaml 写了，不过还是比较啰嗦。。。
@dphdjy 不错

[denghongcai]

@janxin 直接写在注释里面，顺手就写了

web ui 太丑陋，得自己改改

[mozutaba]

@denghongcai +1 ， Google ， IBM 都用的。

[DoLinux]

帮顶。
是 ccj 吗

[sherwinkoo]

apiDoc ，这个工具本身就是用 nodejs 写的，我们公司现在在用，简单方便，试试看。链接： http://apidocjs.com/

[ldw4033]

RAML

[Hayesz]

推荐 swaggerui