这是一个创建于 3176 天前的主题，其中的信息可能已经有所发展或是发生改变。
之前写过一个后台文档，感觉很随意，很想把文档这个事正规起来，不知道有什么适合 NodeJS Web 后台写文档的架子 /平台 /方法 /...
当然，最终优先考虑 Markdown 格式，其它方便的话也可以
补充：文档主题是网络 API 描述 /参数 /例子 /...
 |
1
int64ago OP 比较急，所以无奈自顶
|
 |
2
BiggerLonger 2016-03-15 21:27:05 +08:00  1
Sphinx
|
 |
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 不过感觉看起来也不是特别直观。 |
|
4
int64ago OP @angelface 确实不是很直观
刚刚 Google 了一圈，看到 http://tripit.github.io/slate/?python#introduction 挺符合我要求的，正在看他们项目的 README.md ，如果这里看不到更好的方案我就用这个了 |
 |
5
feiyuanqiu 2016-03-15 22:20:35 +08:00 via iPhone 1
我之前弄了一个，通过解析接口的 validator 规则生成入参的 docblock ，解析接口的 docblock 生成文档 api 参数，模拟登陆我们的文档系统，把生成的文档 post 上去，授权...工作流程就是写完接口原型，然后执行下这个工具就把接口文档弄好了…看起来挺美好，但同事们开发环境不统一，用不了工具，最后就变成谁写完接口就喊我给他加文档，简直烦躁
最近接口文档管理换成 rap 了，要准备适配它的接口格式，用了一下，真是难用，说是秒存，竟然是把所有文档数据一起往服务器传，一个巨大的 json 字符串…多人编辑同一个文档的时候用乐观锁，一直到编辑完保存的时候才告诉你也有其他人在编辑这个，你不能保存，然后就一直报异常，所有人都编辑不了了，开始我还以为是公司里谁闭门造车搞出来的呢，结果一搜好像还是阿里开发的... |
 |
6
ryanking8215 2016-03-15 22:26:43 +08:00 2
mkdocs ， upyun 用它来生成 api 文档页面。
|
|
7
angelface 2016-03-15 23:38:41 +08:00
@ryanking8215 这个不错， 有了 table 可以做不少事儿。
|
 |
8
denghongcai 2016-03-15 23:59:28 +08:00 1
|
 |
9
dphdjy 2016-03-16 01:02:49 +08:00 via Android 1
写个 yaml/swagger 的标准接口~剩下随便找工具生成就好了
|
 |
10
hpu423 2016-03-16 09:26:48 +08:00 1
|
 |
11
janxin 2016-03-16 11:19:03 +08:00
@denghongcai swagger 除了写起来很烦其他都挺好
|
 |
12
Lucups 2016-03-16 11:20:43 +08:00
|
|
13
denghongcai 2016-03-16 11:28:17 +08:00
|
 |
14
mozutaba 2016-03-16 11:54:44 +08:00
@denghongcai +1 ， Google ， IBM 都用的。
|
 |
15
DoLinux 2016-03-16 13:39:28 +08:00
帮顶。
是 ccj 吗 |
 |
16
sherwinkoo 2016-03-16 14:10:37 +08:00 1
apiDoc ，这个工具本身就是用 nodejs 写的，我们公司现在在用，简单方便，试试看。链接： http://apidocjs.com/
|
 |
17
ldw4033 2016-03-16 14:23:24 +08:00 1
RAML
|
 |
18
Hayesz 2016-03-16 15:12:29 +08:00 1
推荐 swaggerui
|
Select Language