API 接口文档应该包含哪些内容
接口文档应该怎么写?要包含哪些内容,好的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/json
、application/x-www-form-urlencoded
、multipart/form-data
、application/xml
,关于 Content-Type 的具体介绍请看:Content-Type介绍
举例(使用 易文档 编写):
4. 请求参数
请求参数是最重要的,基本每个接口都需要这部分,请求参数又分好几种类型:
链接参数,例如/api/v1/user/:userid
,在链接中包含了一个用户id的参数。
Query参数,例如:/api/v1/user?userid=123
,问号后面的参数我们叫query参数。
Body参数,也叫请求体参数,例如文件上传,提交表单,我们通常都是把数据放在body参数中
我们应该把每部分的参数都写清楚,这样一看就知道怎么传递参数了。
易文档 可以自定义参数块,我们创建一个包含3种参数类型看下:
5. 响应参数
响应参数也就是告诉用户我们的接口会返回什么内容,以及返回的格式是什么。
通常我们应该区分成功、失败两种情况分别写清楚返回什么参数。
文档格式上跟请求参数基本一样,直接看例子:
6. 请求示例
最后,为了用户看文档更加清晰明了,我们还可以提供一个完整的请求示例,包含以上描述的5个部分。
易文档可以快速创建一个请求示例,截图示例:
最后,来看一篇完整的 接口文档示例
如果没有好的工具,编写接口文档是特别麻烦的,格式和排版就非常痛苦,易文档提供了专业的接口文档编辑器,可以方便快速的编写出专业漂亮的API文档,还可以做接口测试,一键生成文档,经常写接口文档的小伙伴一定不能错过