微服务接口文档编写规范与版本兼容策略说明.docx

微服务接口文档编写规范与版本兼容策略说明

（IT技术与产品文档·规范与流程写作范例）

第一章接口文档的定位与读者范围

接口文档是把一个微服务对外提供的能力写清楚的可核对文件，读者是前端、调用方与联调测试3类人，不是写给产品经理看的宣传页。一份合格的接口文档要把请求路径、方法、入参、出参、错误码、示例6项分开陈述，每一项都能直接照着生成代码，凡含糊表述如返回若干字段一律退回重写。本文以中型业务系统的5个服务、约80个接口为参照，示例条目均为虚构口径，评审轮次2轮。

判断要不要写正式接口文档看3条线：跨团队调用、接口数量超过20个、单次联调涉及2个以上角色，