如何编写API接口文档

当完成一个API接口时，通常需要与前端人员沟通接口的细节，这时候，一个文档就能节省很多效率，如何书写一份正确的API文档呢，下面是我总结网上大部分人的经验整理的一份说明。

1. 方法描述
   主要说明该方法是实现什么功能的，如用户登录接口
2. URL地址
   例如 /user
3. HTTP请求方式
   该方法需要使用什么方式来请求（GET/POST/PUT/DELETE等）
4. 请求参数
   调用该方法时，需要传递哪些参数值，主要有以下几个方面
   a. 字段（对应的字段名称，如userName,pwd）
   b. 说明（对于该字段的说明，如用户名）
   c. 类型（该字段类型，只能从JSON数据格式中选Array、Number、String、Date等）
   d. 备注
   e. 是否必填(Y/N True/False)
5. 返回结果
   请求该方法预期返回什么样的结果
6. 请求示例
   对该方法做一个请求示例
7. 返回示例
   对该方法做一个返回示例
8. 状态码说明
   对返回的状态码说明，如返回400代表错误，200代表正常

下面做一个简单的示例

• 方法描述：用户登录
• URL地址：/user/login
• 请求方式：post
• 请求参数：

字段	说明	类型	备注	是否必填
userName	用户名	String		Y
passwd	密码	String		Y

• 返回结果

{
  code:100,
  msg:'成功',
  data:{}
}