怎样写好一个接口文档

接口文档书写

1. 前置描述

• 产品文档，简单说明背景，接口用来干嘛的
• 技术文档，说一说各方的具体实现，复杂的可以说下具体的设计思路，n个方案对比，贴上sql，ddl，dml设计，具体代码等具体能看的东西

2. 方法概览

• 方法路径，命名统一
• 方法名称，命名统一
• 方法类型 get/post…

3. 参数定义

• 参数命名统一，下划线，驼峰…
• 类型定义明确，整形，长整型，浮点，对象，指针
• 是否需要枚举 required Enuma a
• 是否必填 optional int a //非必填
• 必要备注，说明这个字段是干啥的 required int a //不能叫a
• 是否需要默认值 required int a =0
• 如果是比较难懂的字段，贴上相关说明链接 required int a //字段说明http:heheda.com
• 如果是部分有特殊意义的string或者数组，举例子说明含义，比如 yyyy-mm-dd类型的string
• 需要提供idl文件的或者webservice，注意格式化
• http请求可以给到示范的请求返回
• 如果是接口变更，用特殊标记表示，比如字体加红