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

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

但是接口文档最重要的一个特性是，接口多，需要给每个接口标序号(如下图)。

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

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

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

Markdown Preview Plus

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

Markdown Viewer

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

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

回答

我推荐 RAML

目前一直在使用，采用 YAML 文件格式编写，强大的官方支持，官方提供 atom 插件，支持语法智能提示及校验，编写快速简单。

支持 examples

支持 schema 校验

支持工具测试

官方提供 API CONSOLE，支持渲染

DEMO APPLICATION

这一切都是免费开源的。

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

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

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

工具的话可以在内网用MinDoc 接口文档在线管理系统搭一个文档管理系统，其功能和界面源于看云，

语法还是Markdown

序号可以以层级关系处理

postman

apidoc 还挺好用的

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

维护省事的就是：Swagger，不过学习成本有点

只是文档性的话，建议：gitbook或mkdocs(都支持markdown语法，和构建为html文件)

APIJSON自动化在线解析

完全自动生成文档，自动管理测试用例，不用写任何代码

http://39.108.143.172/

Showdoc挺好用的

我一般用MD来写，很简单，调用者一看就懂

用户注册

POST /user/register

请求参数

{

"username": "xxx"

}

成功响应

{

"errmsg": "ok",

"errcode": 0

}

失败响应

{

"errmsg": "ok",

"errcode": 0

}

有道云笔记也不错的

公告列表

接口地址：

g=Api&m=Banner&a=lists

返回说明

//正常返回的JSON数据包

{

"result": "ok",

"banners": [

{

"banner_id": "BANNER_ID",

"banner_name": "BANNER_NAME",

"image_url": "IMAGE_URL",

"target_url": "TARGET_URL",

"start_time": "START_TIME",

"end_time": "END_TIME",

"banner_type": "BANNER_TYPE",

"banner_sort": "BANNER_SORT"

}

]

}