4

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

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

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

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

clipboard.png


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

Markdown Preview Plus

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

clipboard.png

Markdown Viewer

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

clipboard.png


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

黒之染 2.9k
2017-12-05 提问
18 个回答
3

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

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

官方提供 API CONSOLE,支持渲染
DEMO APPLICATION
图片描述

这一切都是免费开源的。

2
2

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

2

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

2

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

2

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

序号可以以层级关系处理
图片描述

1

postman

1

团队协作啥的,,一直用这个 https://www.eolinker.com/

1

apidoc 还挺好用的

1

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

1

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

只是文档性的话,建议:gitbookmkdocs(都支持markdown语法,和构建为html文件)

1

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

图片描述

0

Showdoc挺好用的

0

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

用户注册

POST /user/register

请求参数

{
  "username": "xxx"
}

成功响应

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

失败响应

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

有道云笔记也不错的

-1

来源:https://share.notestore.cn/ac...

公告列表

接口地址:

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

撰写答案

推广链接