云、运维与安全 · 前沿
接口文档(API 文档)
写给程序对接用的说明书:讲清一个接口的地址、要传哪些参数、会返回什么、出错报什么。有了它,调用方不用读对方源码也能接上。
TL;DR三十秒版本
- 写给程序对接用的说明书,讲清地址、要传什么、会返回什么。
- 有了它,调用的一方不用去读对方源码,照着填就能接上。
- 它是给程序看的,不是给最终用户看的操作指引。
Overview详细说说
接口文档是写给调用方看的说明书。它讲清楚一个接口的地址是什么、需要传哪些参数、参数的格式和取值范围、成功时返回什么、出错时又报什么。参数往往是有格式要求的,比如日期怎么写、哪个必填哪个可选,这些都要在文档里说死,调用方才不会来回试错。调用方照着它填,就能把请求拼对。
它之所以必须有,是因为软件之间互相调用时,双方往往是两拨互不相识的人,甚至隔着一家公司。没有共同的说明书,就只能靠口头约定或者看代码去猜,对方改一个参数名,另一头就会悄悄坏掉。文档把约定固定下来,双方照着同一份来,改动也有据可查。
你会经常借助 AI 来读它或者写它。把一份接口文档贴给智能体,让它照着调用某个服务,它就能自动拼出正确的请求;反过来,也能让工具扫描项目里已有的接口,自动整理成文档。你听到的 Swagger、OpenAPI,就是描述这类接口的几种常见写法。
别把接口文档和用户手册混起来。前者是给程序对接用的,术语多,讲的是参数、格式、状态码;后者是给最终用户看的,讲的是第一步点什么、第二步填什么。两者读者不同,写法也完全不同,一份顶不了另一份。
Myths常见误解
- ✕以为接口文档就是用户使用手册 ✓前者给程序对接看,讲参数和报错;后者给最终用户看,讲怎么点
- ✕以为有了文档就一定能对接成功 ✓文档对了还得对方真的按它实现,参数对不上、接口改过都会接不通
- ✕以为文档写完就不管了 ✓接口一改文档就得跟着改,不然调用方照旧的填,悄悄就坏了
In practice你会在哪用到它
- 要把两个系统接起来时,先要一份接口文档,照着拼请求
- 把接口文档贴给 AI,让它按里面的参数帮你写调用的代码
- 自己写的接口变了参数,回头更新文档,别让对接的人踩空
Summary记住这几点就够了
- 供软件之间互相对接时看的说明书
- 讲清地址、参数、返回值和报错信息
- 有了它,调用方不用读对方源码就能接上
- Swagger、OpenAPI 是它的常见写法
常见问题
接口文档(API 文档)是什么意思?
写给程序对接用的说明书,讲清地址、要传什么、会返回什么。有了它,调用的一方不用去读对方源码,照着填就能接上。它是给程序看的,不是给最终用户看的操作指引。
接口文档(API 文档)一般用在什么地方?
要把两个系统接起来时,先要一份接口文档,照着拼请求;把接口文档贴给 AI,让它按里面的参数帮你写调用的代码;自己写的接口变了参数,回头更新文档,别让对接的人踩空。
关于接口文档(API 文档),最容易搞错的是什么?
以为接口文档就是用户使用手册,其实前者给程序对接看,讲参数和报错;后者给最终用户看,讲怎么点;以为有了文档就一定能对接成功,其实文档对了还得对方真的按它实现,参数对不上、接口改过都会接不通。
接口文档(API 文档)要记住哪几点?
供软件之间互相对接时看的说明书;讲清地址、参数、返回值和报错信息;有了它,调用方不用读对方源码就能接上;Swagger、OpenAPI 是它的常见写法。
容易踩的坑 接口文档是给程序对接看的,不是给最终用户看的操作说明。
Also written as你可能还会看到这些写法
这些都是同一个概念,在技能介绍里指代的是同一件事 —— 不必因为写法不同而以为是两个东西。
全站第 174 / 186 条 · 全部词条
接着读Related reading
DevOps(开发运维一体化)
让写代码的和管服务器的人共用一套流程和工具,把测试、打包、上线交给机器自动完成,改完代码很快就能安全发布。
镜像(Image,软件打包模板)
把软件和它运行需要的环境一起打包好的模板,取出来在任意一台机器上都能跑出一样的结果。
HTTPS(加密网页协议)
给浏览器和网站之间的通信上锁加密,网址前面那个小锁就是它;路上有人偷看,也只能看到一串乱码。
漏洞(安全漏洞)
软件里一处能被坏人利用的缺陷,能让对方做本不该被允许的事,比如偷数据、冒充管理员或把程序弄崩。
会话(Session)
服务器用来记住这一段连续互动还是同一个人的方式;从你登录到退出之间的操作,被串成一整条记录。
Linux(操作系统)
免费开源的电脑操作系统,全球大多数服务器都在跑它;通常没有图形界面,但稳定、省资源、能长期不关机。