接⼝⽂档⽰例_技术·⽂档标准API⽂档规范1.0
背景
随着业务的发展，⽀撑平台的项⽬也是越来越多。
同时，为了让业务系统更加清晰，会从整个平台项⽬的架构体系，对系统业务⽔平拆分、垂直分层，产⽣了⼀系列平台和⼦系统，并使⽤接⼝进⾏数据交互。
伴随着业务的发展，接⼝⽂档会越来越多。
那么痛点在哪⾥？
代码和⽂档不匹配，代码接⼝更新，⽂档不更新，且接⼝⽂档内容和形式百花齐放，不便于理解。
撸码⼀分钟，对接三⼩时
为了解决这些痛点，我们定义了如下接⼝⽂档规范，⽤于编写API接⼝时的指导，以便于你写出良好规范的API⽂档。
API⽂档概述
什么是API
API（Application Programming Interface）即应⽤程序编程接⼝，是⼀些预先定义的函数，是连接客户
端与服务端的桥梁，可以为应⽤程序与开发⼈员提供基于某软件或硬件得以访问⼀组例程的能⼒，⽽⼜⽆需访问源码，或理解内部⼯作机制的细节。
什么是API⽂档
API⽂档是⾯向API使⽤者对API功能、⽤法和版本等信息等详尽描述，API⽂档增加了API等易⽤性，是API开发者⾯向使⽤者对公开约束。什么是好的API⽂档
好的API接⼝⽂档对于使⽤者来说必须满⾜以下⼏个点：
易学习：
· 易学习
有完善的⽂档及提供尽可能多的⽰例，⽂档要遵循⾏业和国际标准，让有经验和背景的调⽤者可以快速上⼿。
例如，定义国家代码，要使⽤ISO-3316国家代码标准中的国家代码，中国是“CN”，⽽不是⾃⼰造⼀个“CHI”，以免造成误解。
易使⽤：
· 易使⽤
对于读者来说，⽂档没有复杂的程序和业务细节，只要易于读者学习即可。
灵活的API允许按字段排序、可⾃定义分页、 排序和筛选等。⼀个完整的API意味着被期望的功能都包含在内。
难误⽤：
· 难误⽤
详细的错误提⽰，⽤户可从⽂档的阅读中了解API的使⽤⽅法和误区，不会在调⽤API的时候出现“惊喜”。
兼容性
· 兼容性
API的升级要考虑向下兼容，⽂档也要考虑前后⼀致。
例如尽量避免在版本1是必填的参数，在版本2改为⾮必填，等等。
实时性
· 实时性
⽂档也相应地要考虑随着版本的更新⽽更新，且与服务⼀致。
避免客户端根据⽼的⽂档⽽请求新的接⼝⽽造成与预期不⼀致。
API⽂档⽬录
下⾯定义了标准的接⼝⽂档⽬录格式：
1.修订历史
2.接⼝描述
3.服务接⼊
基本信息
服务信息
4.请求和返回参数
请求参数
返回参数
5.成功和异常⽰例
成功⽰例
请求参数
返回参数
异常⽰例
请求参数
返回参数
6.状态码
错误码
业务码
百度api接口
API⽂档⽰例
下⾯提供了标准的接⼝⽂档的简要⽰例，可以在创建API⽂档的时候参考此结构和⽰例。
修订历史
倒序排列。
以下为本⽂档对修订历史，倒序排列
原则上，⽆论API发⽣了任何定义、约束和功能上的变更，都应该体现在以下修订历史中，同时强烈建议在接⼝发⽣变更以后升级版本，并尽可能保证向下兼容（即如果客户端没有更新API也可以正常使⽤之前的功能）。
接⼝描述
以下为⽂档的概要描述，简要说明了此接⼝提供的能⼒、覆盖的业务场景、相关的系统⾓⾊等。
服务接⼊
此处描述了接⼝的形式（RPC、HTTP等）、接⼝的地址、客户端等配置等信息。服务信息
如果是请求RPC接⼝，需要增加如下描述。
· 服务AppId：AppPAyService
· 接⼝：ample.pay.TransferService
· ⽅法：transfer
· maven依赖
开发联调时使⽤SAPSHOT版本，上UAT前需要更换最新RELEASE版本
<dependency>
<groupId&le.pay</groupId>
<artifactId>pay-transfer</artifactId>
<version>最新RELEASE版本</version>
</dependency>
· 接⼝定义
public interface TransferService {
Response<Result> transfer(Request request);
}
详细内容⽅位：
技术·⽂档 | 标准API⽂档规范 1.0

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。