接口文档应该怎么写?要包含哪些内容,好的API文档模板应该是怎样的,怎样才能快速编写专业漂亮的接口文档,这篇文章给你解答。

一个完整的接口文档,应该包含以下几个部分:

  • 请求地址,也就是 URL
  • 请求方法,常见的有:GET,POST,PUT,DELETE,PATCH,UPDATE
  • 请求头,通常用来传递一些公用参数,token等,如果没有内容也可以省略这部分
  • 请求参数,请求参数又分为好几种,后面详细介绍
  • 响应参数,最好区分成功和失败等不同情况的响应内容
  • 请求示例,这部分可选,有的话能让对方更好的理解怎么使用。

下面,我们详细的介绍下每个部分应该怎么写。

1. 请求地址

举例:https://easydoc.net/api/v1/user/login
请求地址中,我们应该写清楚协议,也就是使用http还是https,有些平台已经是强制只能使用https了,因为更加安全。

2. 请求方法

请求方法有很多同,但是最常用的是GET,POST,如果使用 RESTful 规范,还会使用到 PUT,DELETE等其他请求方法。
请求方法上,最明显的区别是 GET 的参数只能在地址中,其他请求方法可以在请求体中传递参数。
我们写文档时,一般把请求方法写在地址前面
举例:POST https://easydoc.net/api/v1/user/login

3. 请求头

请求头通常用来传递一些公用的参数,比如Content-Type,Cookie,Authorization等。
其中Content-Type是每个接口都应该写清楚的,这个表示我们接口接受什么格式的参数,常见的有以下几种:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/xml,关于 Content-Type 的具体介绍请看:Content-Type介绍
举例(使用 易文档 编写):
接口文档头部参数示例

4. 请求参数

请求参数是最重要的,基本每个接口都需要这部分,请求参数又分好几种类型:
链接参数,例如/api/v1/user/:userid,在链接中包含了一个用户id的参数。
Query参数,例如:/api/v1/user?userid=123,问号后面的参数我们叫query参数。
Body参数,也叫请求体参数,例如文件上传,提交表单,我们通常都是把数据放在body参数中
我们应该把每部分的参数都写清楚,这样一看就知道怎么传递参数了。
易文档 可以自定义参数块,我们创建一个包含3种参数类型看下:
API文档请求参数易文档示例

5. 响应参数

响应参数也就是告诉用户我们的接口会返回什么内容,以及返回的格式是什么。
通常我们应该区分成功、失败两种情况分别写清楚返回什么参数。
文档格式上跟请求参数基本一样,直接看例子:
API文档响应参数易文档示例

6. 请求示例

最后,为了用户看文档更加清晰明了,我们还可以提供一个完整的请求示例,包含以上描述的5个部分。
易文档可以快速创建一个请求示例,截图示例:
API文档请求示例

最后,来看一篇完整的 接口文档示例
如果没有好的工具,编写接口文档是特别麻烦的,格式和排版就非常痛苦,易文档提供了专业的接口文档编辑器,可以方便快速的编写出专业漂亮的API文档,还可以做接口测试,一键生成文档,经常写接口文档的小伙伴一定不能错过