我有一个朋友，这是他公司实施的 YAPI 接口文档编写规范，屏蔽了一些涉及技术隐私的规范

接口文档编写规范

1. 枚举值
   1. 枚举值参数统一在备注中使用$$后缀注明
   2. 于项目中的公共分类中创建/enum 目录，录入枚举值
2. 参数
   1. 参数英文名称需与中文注释保持一致
   2. 参数需注明参数类型
   3. 参数需注明是否必填
   4. 参数需提供 mock 值
   5. 时间型参数用秒级时间戳形式的整型表示
   6. ID 型参数用字符串表示
   7. 日期型参数用"YYYY-mm-dd"形式的字符串表示
   8. 不下发 null, 用对应类型的空值替代
   9. 对象的空值是空对象
   10. 数组的空值是空数组
   11. 数值型的空值是 0
   12. 字符串型的空值是空串
   13. 公共参数不应在接口中出现
   14. 新项目中，GET 请求使用查询参数，POST 请求使用 JSON 参数
3. 布尔值
   1. 布尔类型统一以整型进行上传和下发
   2. 0 表示假，1 表示真
   3. 布尔型参数统一使用_flag 后缀进行命名，如 valid_flag
   4. 命名方式需采用肯定形式，禁止采用双重否定
4. 备注
   1. 对接口的每次更改，需于备注中进行注明新增/修改的参数
   2. 接口的使用若复杂难懂，需于备注中进行注明
5. 接口名称
   1. 采用动宾结构
   2. 例外情况：登录、注册等固定搭配
   3. 已废弃的接口于名称后尾标注“(已废弃)”,并于接口备注说明废弃版本号
6. 接口请求方式
   1. 只存在 GET 和 POST
   2. 语义上更偏向获取信息的用 GET
   3. 对安全性要求高，涉及到数据变更，需使用请求体传输数据的用 POST
7. 接口路径
   1. 函数式命名风格，动宾搭配
   2. 获取列表以 list_开头，并采用单数，如 list_user
   3. 获取单个数据以 show_开头
   4. 创建数据以 create_开头
   5. 更新数据以 update_开头
   6. 删除数据以 delete_开头
   7. 资源型命名空间采用复数命名，整体路径如"/api/v1/users/list_user"
8. 接口状态
   1. 当接口与测试服一致时，为已完成
   2. 当处于实现中或代码修改中，为未完成
9. 标签
   1. 每次新增或修改接口，需打上版本号标签，如"2.0.3", 不带 V
   2. 对于以 H5 为主的项目，需打上"原生"标签，注明为原生调用的接口
   3. 对于以原生为主的项目，需打上"H5"标签，注明为 H5 调用的接口
   4. 对于免登录的接口，需打上"免登录"标签
10. 分类名
    1. 分类名为中文单词 + (英文复数), 如"评论 (comments)"
11. 环境配置
    1. 环境配置需配置开发、测试、正式三个环境
    2. 请求配置需配置预处理代码，便于后台人员在线运行接口
12. 测试集合
    1. 每次迭代，涉及的接口需创建测试集合放置
    2. 上线测试服，测试集合应能看到对应的调用结果
13. 公共分类
    1. 需统一公共参数 /common_params
    2. 需统一说明枚举值 /enum
    3. 需统一说明接口响应码 /code
    4. 其他说明文档也放置于公共分类，如云存储空间说明等
14. 请求头
    1. 按需设置请求头
15. 接口设计
    1. 设计时需思考调用是否符合人类直觉
    2. 设计时需思考参数设计是否能应对需求变更
    3. 设计时需思考前端调用接口是否方便
    4. 设计时需思考对于扩展是否方便
    5. 设计时对接口涉及的改动信息需及时在讨论群组中说明并记录在文档中