POST接口定义示例 - 清晰实用的API文档写法

做前后端联调的时候，最怕啥？不是bug，是接口文档写得不清不楚。特别是POST请求，传什么字段、格式怎么写、返回啥结构，全靠猜。今天就拿一个实际场景说说，怎么写一个清晰明了的POST接口定义。

场景：用户注册接口

假设你在开发一个网站，需要提供用户注册功能。前端要提交用户名、密码、邮箱，后端接收并存入数据库，成功返回用户信息，失败返回错误原因。

完整的POST接口定义长这样

接口地址：/api/v1/register
请求方法：POST
请求类型：application/json

请求参数（body）

{
  "username": "zhangsan",
  "password": "123456",
  "email": "zhangsan@example.com"
}

成功返回示例

{
  "code": 0,
  "msg": "注册成功",
  "data": {
    "id": 1001,
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "created_at": "2024-04-05T10:00:00Z"
  }
}

失败返回示例

{
  "code": 400,
  "msg": "邮箱格式不正确",
  "data": null
}

字段说明表

光有示例还不够，最好配上字段说明：

字段名	类型	必填	说明
username	string	是	用户名，长度3-20字符
password	string	是	密码，建议加密传输
email	string	是	邮箱地址，需符合邮箱格式

这样的接口文档，前端一看就懂，调试起来也省事。别再只写一句“提交数据”，具体字段、格式、返回结构都列清楚，团队协作效率能高一大截。