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

Question

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

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

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

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

---

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

Markdown Preview Plus

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

Markdown Viewer

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

---

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

Answer 1

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

1. 支持 examples
2. 支持 schema 校验
3. 支持工具测试

官方提供 API CONSOLE，支持渲染
DEMO APPLICATION

这一切都是免费开源的。

Answer 2

https://swagger.io/

Answer 3

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

Answer 4

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

Answer 5

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

Answer 6

http://apizza.cc/?f=chromeapp

Answer 7

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

Answer 8

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

序号可以以层级关系处理

Answer 9

postman

Answer 10

apidoc 还挺好用的

Answer 11

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

Answer 12

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

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

Answer 13

APIJSON自动化在线解析
完全自动生成文档，自动管理测试用例，不用写任何代码
http://39.108.143.172/

Answer 14

Showdoc挺好用的

Answer 15

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

用户注册

POST /user/register

请求参数

{
  "username": "xxx"
}

成功响应

{
  "errmsg": "ok",
  "errcode": 0
}

失败响应

{
  "errmsg": "ok",
  "errcode": 0
}

Answer 16

有道云笔记也不错的

Answer 17

来源：https://pinapp.gitee.io/w3/api/

公告列表

接口地址：

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"
        }
    ]
}