适合写接口文档的工具，或者文本语法

Question

由于后端与前端使用ajax交互，后端写接口文档变得非常有必要。以前我习惯用word写接口文档，但是最近与同事合作编写后端，word并不适合使用svn工具做同步，因为svn、git等无法自动合并word。所以打算把文档写成文本的格式。

一开始想到的是用markdown语法来写。markdown语法大全

但是接口文档最重要的一个特性是，接口多，需要给每个接口标序号（如下图）。
当然markdown支持序号，但是支持得并不完美，比如上下两个序号之间最多只能有一个空行，并且空行不能写文字，这样就只能光写接口标题了，没有空间写接口内容了。

请问适合写接口文档的方法是什么？最好就是一种语法，而不是一个软件

---

感谢大家的回答，考虑到markdown目前的趋势，还是决定继续使用markdown，现在已经想到解决办法，markdown只是一种语法，到底怎么显示，还是由软件或者浏览器插件来决定的，我找到两款chrome插件

Markdown Preview Plus

能自动把原文中的标题提取出来生成目录，并且能给目录自动加序号（如果原文标题本身就有序号，它也会加自己的序号，所以原文标题不能有序号）

Markdown Viewer

同样能把原文中的标题提取出来生成目录，但是不会加序号，对于不需要序号，或者接口较少的，可以用这个，我更喜欢这个插件的目录样式，可惜功能缺了一点。

---

这两款插件其实是提供给文档阅读者的，文档编辑者倒是可以不需要，全看个人喜好了，chrome官方市场里就找到这两款了，不知道国内有没有人开发了插件没传到chrome市场

Answer 1

GitBook或者Swagger-UI都可以。比较推荐Swagger-UI，在写代码的时候添加注释即可生成文档。

Answer 2

选过去选过来 还是觉得使用postman要顺手一点 反正这东西都要手写 postman调试起来还方便

Answer 3

eoLinker接口管理平台 | 全球领先API接口管理平台，Google谷歌开发者联盟合作项目企业相当不错

Answer 4

一直在用RAP，使用起来很简单RAP

Answer 5

工具的话可以在内网用MinDoc 接口文档在线管理系统搭一个文档管理系统，其功能和界面源于看云，语法还是Markdown 序号可以以层级关系处理

Answer 6

postman

Answer 7

Swagger. 通过固定格式的注释生成文档. 省时省力

Answer 8

维护省事的就是：Swagger，不过学习成本有点 只是文档性的话，建议：gitbook或mkdocs（都支持markdown语法，和构建为html文件)

Answer 9

我一般用MD来写，很简单，调用者一看就懂 用户注册 POST /user/register 请求参数 { "username": "xxx" } 成功响应 { "errmsg": "ok", "errcode": 0 } 失败响应 { "errmsg": "ok", "errcode": 0 }

Answer 10

有道云笔记也不错的