分享接口设计文档的12个注意点

千宇君_9976

千宇君_9976

2023-04-24

2876人浏览

转载

前言

我们做后端开发的,经常需要定义接口文档。

最近在做接口文档评审的时候,发现一个小伙伴定义的出参是个枚举值,但是接口文档没有给出对应具体的枚举值。其实,如何写好接口文档,真的很重要。今天田螺哥,给你带来接口设计文档的12个注意点~

image.png

  • 公众号:捡田螺的小男孩 (有田螺精心原创的面试PDF)
  • github地址,感谢每颗star:github

1. 你的接口名称是否清晰?

换句话说,你的接口是做什么的,是否易懂清晰?一般接口url也要求能看得出接口的作用。比如说,查询用户信息(queryUserInfo),就是一个不错的接口名称。

image.png

2. 你的接口地址是否完整

接口的地址,也叫接口的URL地址。即别人调用你的接口,用的是什么URL。比如/api/user/queryUserInfo就是一个接口地址。但是,我想说的是,这还不是一个完整的接口地址。你的接口是不是HTTP调用呢?

如果是HTTP调用的话,域名是什么呢?端口呢。一个好的http接口地址,应当是这样的:

https//tianluo.com:15000/api/user/queryUserInfo

image.png

3.你的接口请求方式是否正确

接口请求方式通常有以下几种:

  • GET:从服务器获取资源,可以在URL中传递参数,通常用于查询数据。
  • POST:向服务器提交数据,通常用于新增、修改、删除等操作。
  • PUT:向服务器更新资源,通常用于更新数据。
  • DELETE:从服务器删除资源,通常用于删除数据。
  • PATCH:向服务器局部更新资源,通常用于修改部分数据。
  • HEAD:类似于GET请求,但是只返回响应头,不返回实体内容,通常用于获取资源的元信息。
  • OPTIONS:请求服务器返回支持的请求方式等信息,通常用于客户端与服务端协商请求方式。

你定义接口文档的时候,需要写清楚,你的接口请求方式是哪一个?一般情况下,我们用POST和GET比较多。也有些公司的所有接口都用POST请求。

image.png

4.请求参数的8大要素

我们定义接口的时候,请求参数是最主要的部分之一。一份合格的接口文档,请求参数应当包含这八大要素:

  • 参数名: 参数的名字,都是驼峰命名,比如userId。
  • 类型: 参数的类型,比如String、Integer等。
  • 是否必填: 请求参数是不是必填的,如果要求必填的,当上游不传这个参数的时候,应当抛参数校验异常。
  • 默认值: 如果这个参数不传,是否有默认值,默认值是多少。
  • 取值范围: 如果是Long,Integer等数值类型的话,这个就是一个范围值,比如1~10,如果是枚举值的话,那就是枚举范围,比如ACTIVE、INACTIVE。
  • 参数格式:比如你的参数是个日期的话,就需要说明参数格式,如yyyyMMdd
  • 入参示例值: 提供该响应参数的示例值,以便开发人员更好地理解和使用该参数。
  • 备注: 如果这个入参字段有特殊说明的话,可以在这一栏说明。如果没有特殊说明,那只描述这个参数作用也可以。

以下就是入参的文档样例:

参数名 类型 是否必填 默认值 取值范围 参数格式 入参示例值 备注(说明)
userId Long 是 0L 0~99999999L 无 666L 用户Id
birthDay String 是 19900101 19900101~20231231 yyyyMMdd 19940107 用户生日

image.png

5.响应参数的7大要求

响应参数其实跟入参差不多,有7种要素:

  • 参数名称:描述该响应参数的名称。
  • 参数类型:描述该响应参数的数据类型,如String、Integer等。
  • 参数格式:描述该响应参数的数据格式,如yyyy-MM-dd、HH:mm:ss等。
  • 参数说明:对该响应参数的含义进行详细的描述。
  • 取值范围:描述该响应参数的取值范围,如整数范围、字符串长度等。
  • 是否必填:描述该响应参数是否为必填项。
  • 示例值:提供该响应参数的示例值,以便开发人员更好地理解和使用该参数。

不一样的地方是,响应参数,一般都是按照code,msg,data的格式返回的:

btpanel phpsite 宝塔面板PHP网站
btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理:站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载
{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

6. 接口错误码

一份好的接口文档,一定少不了错误码列举。一般错误码定义包括三列:错误码、错误码信息、含义

错误码 错误信息 含义
1001 参数错误 请求参数不合法
1002 用户不存在 根据给定的用户ID没有找到对应的用户信息
1003 数据库错误 数据库访问出错

image.png

7.接口安全

定义接口文档时,对于一些需要保护的接口,也需要考虑接口的安全,例如权限管理、防止 SQL 注入等。

因此,接口文档应当包含接口的安全性说明:例如接口的访问授权方式、数据传输加密方式等。此外,接口文档还应该对于敏感数据和操作进行标注,方便使用者注意隐私和安全问题。

image.png

8. 接口版本管理

在接口文档定义时,接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级,接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰,需要对接口进行版本管理。

以下是一些常用的接口版本管理方法:

  • 在接口文档中明确版本号:在接口文档中明确标识接口的版本号,例如在接口地址中添加版本号信息,如https://example.com/api/v1/user,表示该接口的版本号为v1。
  • 使用语义化版本号:采用语义化版本号(Semantic Versioning)规范,即版本号格式为X.Y.Z,其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时,需升级主版本号;当增加功能且不影响现有功能时,需升级次版本号;当进行bug修复或小功能改进时,需升级修订号。
  • 增量发布:在接口发生变化时,先发布新版本的接口,同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口,最终可以将旧版本的接口废弃。

无论采用何种方法,接口版本管理都应该得到充分的考虑。在接口版本变化时,需要及时更新接口文档(详细描述版本的变化、兼容性问题、版本切换方式等),以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更,比如参数有哪些变更,错误码变更等等,都需要维护到文档上。同时需要登记变更的记录。

日期 变更描述 操作人
2023-04-16 创建接口文档,定义了第一版接口文档 捡田螺的小男孩
2023-04-18 修改接口文档,增加了错误码,出参等 田螺哥

image.png

10.明确请求头有哪些

接口文档,是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息:

  • Content-Type:指定请求体的数据格式,如application/json、application/x-www-form-urlencoded、multipart/form-data等。
  • Authorization:用于身份验证的令牌信息,如Token、Bearer等。
  • Accept:指定客户端可以接受的响应数据格式,如application/json、text/html等。
  • User-Agent:指定客户端的类型和版本信息,可以用于服务端进行针对性优化。
  • Accept-Encoding:指定客户端可以接受的数据压缩格式,如gzip、deflate等。
  • Cache-Control:指定客户端缓存的策略,如no-cache、max-age等。
  • Cookie:包含客户端发送给服务器的cookie信息。

这是是一个接口文档的请求头的示例:

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11 接口请求示例

接口文档,需要提供接口的使用案例:以方便开发者理解接口的使用方法和调用流程。

12. 接口测试

一般来说,接口文档需要完善:接口测试的方法和测试结果,以便用户可以测试接口是否符合自己的需求,让用户用得放心~哈哈

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

相关标签:

php

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

20

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

20

15

GoFrame框架零基础入门
GoFrame框架零基础入门

本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。

2026.11.17

20

15

SQLAlchemy 一对多关系怎么建立
SQLAlchemy 一对多关系怎么建立

SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。

2026.11.17

20

10

SQLAlchemy 如何增删改查
SQLAlchemy 如何增删改查

SQLAlchemy 如何增删改查?本专题整理 ORM 新增记录、条件查询、更新和删除、Session 事务提交与批量处理等实用文章,帮助你掌握 Python 数据库操作流程。

2026.11.17

20

11

SQLAlchemy ORM 模型怎么写
SQLAlchemy ORM 模型怎么写

SQLAlchemy ORM 模型怎么写?本专题整理模型类定义、Mapped 字段映射、主键与约束、表结构创建和常见报错的相关文章,帮助你从基础配置到实际建模逐步掌握 SQLAlchemy。

2026.11.17

20

16

Go-Zero API开发使用教程
Go-Zero API开发使用教程

本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

2026.11.12

180

15

Go-Zero安装与goctl环境配置教程
Go-Zero安装与goctl环境配置教程

本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.12

120

15

Go-Zero零基础入门教程
Go-Zero零基础入门教程

本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。

2026.11.12

120

15

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
Docker Desktop设置与维护手册
Docker Desktop设置与维护手册

共0课时 | 0人学习

LLVM官方文档
LLVM官方文档

共0课时 | 0人学习