关于 RESTful 的 「API 文档」

Question

团队在用 Java Jersey 做 RESTful Web Service，随着接口的增加，文档化越来越重要。正在了解

• Swagger
• I/O Docs
• Carte
• RAML

有朋友用过，或者有其他推荐？

Answer 1

个人觉得swagger比rap要好很多 rap的作者是阿里的霍雍 swagger在国外用的比较火，而且适用场景比较多，
单独为楼主弄了一个项目 基于swagger-ui springmvc 项目一下来就可以跑起来，我做了最简的优化，很容易去理解swagger-ui以及去改造它，它有权限控制等，mock数据有待开发，一切都是根据注解去书写文档，保证了文档和代码的一致性。
项目地址：https://github.com/mousycoder/server-api
希望楼主可以试试，或者我们可以一起开发。

Answer 2

Swagger
可在线调试很方便

Answer 3

试一下阿里的rap写接口文档，我们公司在用，还可以

Answer 4

看云－在线文档托管
现代化的UI，多级分类，单篇锚点，全文档搜索，可选的评论，在国内。
thinkphp文档：http://www.kancloud.cn/manual/thinkphp/1678
首页：http://www.kancloud.cn/

Answer 5

我再给一个备选项吧，apiary，用markdown写api文档

Answer 6

最终我们团队还是选择了 Swagger，虽然它的「侵入式」太强……
从团队协作的角度，使用 Swagger 之后前期的设计更加集中于「接口」本身，而不是具体的实现，后台的兄弟首先完成 Swagger 接口定义并发布到开发环境，App/Web 端直接按照接口联调就行了，还是蛮方便的。
从设计效率来看，Swagger 还是太重了，要花大量的时间在 Annotation 上。接下来准备尝试 json-rest-server 或 json-server

Answer 7

来挖个坟。

@gucs
@spacelan

【侵入式】不强的，

api-blueprint
前端渲染出来不比swagger难看，同时同时！他是基于Markdown语言定义的。
同时sublimet 和 atom 都有成熟插件支持个性化语法

在线版请戳

这上手速度估计甩swagger几条街吧，很早之前就关注过在线版，没想到居然开源了。

Answer 8

重要的不是工具，而是文档本身