什么是接口文档,如何写接口,有什么规范? |
您所在的位置:网站首页 › vp接口 › 什么是接口文档,如何写接口,有什么规范? |
“你这接口文档,谁能看懂,写的都是啥,能调通才怪呢!浪费我时间” “你到底会不会看文档啊,调用方式,参数我都给你写了,你也太菜了吧!” “你...” 看到这,大家可能都知道咋回事了。前后端分离开发就是这样,需要前后端友好的沟通,更需要一个容易理解的接口文档,方便前端人员开发!不然就可能发生上述互喷的情况。 关于什么是接口文档其他答主已经解释得很清楚了,在这里我就不再赘述了。我主要讲讲衡量接口(API)设计好和坏的准则和一些规范。 槽糕的API接口五花八门,但是好的API接口对于用户来说必须满足以下几个点: • 易学习:有完善的文档及提供尽可能多的示例和可copy and paste的代码,代码应该尽可能地减少多余的“惊喜”部分。换句话说,你写的代码只需要按照项目要求来编写即可,不用其他华丽的装饰。 • 易使用:对于读者来说,代码没有复杂的程序、细节,只要易于读者学习即可。灵活的API允许按字段排序、可自定义分页、 排序和筛选等。一个完整的API意味着被期望的功能都包含在内。 • 难误用:详细的错误提示,有些经验的用户可以直接使用API而不需要阅读文档。 而对于开发者来说,要求又是不一样的: • 易阅读:虽然代码的编写只需要进行一次,但是当调试或者修改的时候都需要对代码进行理解阅读。 • 易开发:最小化的接口是使用最少的类和最少的类成员,但能达到相同的效果。这样使得理解、记忆、调试以及改变API更容易。 API规范 接口名称:这里统一使用小写 如:api/order/get可参考跟着Github学习Restful HTTP API 设计 uri:提供客户端使用的全路径如http://172.16.0.194:8057/api/order/get 请求协议:Http,Https请求方式:POST,GET等头部(系统参数):加密签名,时间戳等请求参数(业务):业务相关的输入参数响应参数(业务):输出参数返回示例:定义返回结果数据结构,更直观 1.返回成功 2.返回失败 具体设计原则可以参考一下wangpeng047这位博主的一些观点:如何正确合理的设计一个接口项目 关于优雅的接口怎么设计,可以参考这篇文章:【Java工程师必备素质】你设计的接口,够优雅吗? 我是 BinSTD,国内领先的 Token 化数据 API 交易平台。 |
CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |