如何写好一份接口文档

一份好的接口文档，首先需要做到的是 清晰明确, 从而 消除不确定性、减少沟通成本，本文主要阐述的是作者在跨团队合作中，输入接口文档的一些规则

服务名

XXXSerivce

接口负责人

如果读者有疑惑，可以通过接口负责人进行沟通

POM 坐标

大部分的项目都是使用maven作为jar包管理工具，我们需要提供sdk的pom坐标，以及提供的sdk是release版本 (正式版本，线上正在使用的、稳定的版本)还是snapshot版本(快照版本，用于测试或联调)

服务说明

简述服务的功能，和实现原理。着重需要说明的是：

1. 是B端接口还是C端接口，严禁BC端接口混用
2. 是否可以支持异步调用，比如接口中会将重要信息与线程绑定(例如 threadlocal)，这个时候就不能异步调用
3. …  （根据实际情况扩展）

重要程度

是否可降级？ 如果接口不可用，是否会影响到主流程等等…

假设该接口不调用，会导致下游逻辑不自洽，这种情况一定要标注出来

异常处理

这里的异常有两种情况：

1. 接口本身抛出的业务异常
2. 由于网络问题导致的调用超时等

需要给出上游调用方的处理方式，是可以忽略，还是需要对异常进行何种处理，是否可以重试等等，可以给出自己的处理建议

使用示例

如果调用方式比较复杂的话，可以给出一个简单的使用示例

参数说明

入参：字段、类型、是否必填、说明

出参：字段、类型、说明

接口能力

目前接口的QPS、p99等信息

监控地址

如果有监控面板，可以附上

以上就是作者认为接口文档需要具备的信息，如有不同观点，欢迎评论区交流，感谢阅读~