接口文档编写注意事项

接口文档编写注意事项

字段方面

①不需要的字段、逻辑中固定值的字段（可写死的字段）不提供
②逻辑上可以合并的字段合并
例如：当一个互斥条件下，分别返回了两个字段，这个时候就可以在这个基础上将两个字段合并成一个字段
③字段对应的业务逻辑要标清楚
例如：某些情况下，响应返回的某个字段，在不同的情况下返回的结果是不一样的，调用方根据这个字段返回值需要有不同的响应，这个时候就需要标注下，该字段不同的响应值，调用方需要做的逻辑

④是否非空，长度，枚举类型标清楚
⑤条件必填对应的原因写清楚

接口方面

①接口调用流程，从哪里调到哪里（调用方/提供方）（请求方/响应方）
②接口是同步还是异步
③接口请求地址

报文

①请求参数
②响应参数
③公共参数
④小对象参数（附加域参数）

应答码

①明确成功状态
②错误码、对应错误原因表格

http

①http请求响应终态码（成功状态码/失败状态码）
②超时时间
③使用json、xml或者其他格式

网络

①专线还是公网
②是否需要白名单，网络准入

安全

①加签验签证书，及加签验签流程
②加密解密证书，及加密解密流程
③证书交换形式：接口/系统/邮件