由于后端与前端使用ajax交互，后端写接口文档变得非常有必要。以前我习惯用word写接口文档，但是最近与同事合作编写后端，word并不适合使用svn工具做同步，因为svn、git等无法自动合并word。所以打算把文档写成文本的格式。
一开始想到的是用markdown语法来写。markdown语法大全
但是接口文档最重要的一个特性是，接口多，需要给每个接口标序号（如下图）。当然markdown支持序号，但是支持得并不完美，比如上下两个序号之间最多只能有一个空行，并且空行不能写文字，这样就只能光写接口标题了，没有空间写接口内容了。
请问适合写接口文档的方法是什么？最好就是一种语法，而不是一个软件
感谢大家的回答，考虑到markdown目前的趋势，还是决定继续使用markdown，现在已经想到解决办法，markdown只是一种语法，到底怎么显示，还是由软件或者浏览器插件来决定的，我找到两款chrome插件
Markdown Preview Plus
能自动把原文中的标题提取出来生成目录，并且能给目录自动加序号（如果原文标题本身就有序号，它也会加自己的序号，所以原文标题不能有序号）
Markdown Viewer
同样能把原文中的标题提取出来生成目录，但是不会加序号，对于不需要序号，或者接口较少的，可以用这个，我更喜欢这个插件的目录样式，可惜功能缺了一点。
这两款插件其实是提供给文档阅读者的，文档编辑者倒是可以不需要，全看个人喜好了，chrome官方市场里就找到这两款了，不知道国内有没有人开发了插件没传到chrome市场
18 回答
largeQ
TA贡献2039条经验 获得超7个赞
我一般用MD来写，很简单，调用者一看就懂
用户注册
POST /user/register请求参数
{
"username": "xxx"
}成功响应
{
"errmsg": "ok",
"errcode": 0
}失败响应
{
"errmsg": "ok",
"errcode": 0
}
- 18 回答
- 0 关注
- 910 浏览
添加回答
举报
0/150
提交
取消