写好接口文档的方法


本文摘自PHP中文网,作者小云云,侵删。

本文主要和大家分享如何写好接口文档的方法,希望能帮助大家写好一个接口文档。

1 HTTP携带信息的方式

  • url

  • headers

  • body: 包括请求体,响应体

2 分离通用信息

一般来说,headers里的信息都是通用的,可以提前说明,作为默认参数

3 路径中的参数表达式

URL中参数表达式使用mustache的形式,参数包裹在双大括号之中{{paramName}}

例如:

  • /api/user/{{userId}}

  • /api/user/{{userType}}?age={{age}}&gender={{gender}}

4 数据模型定义

数据模型定义包括:

  • 路径与查询字符串参数模型

  • 请求体参数模型

  • 响应体参数模型

数据模型的最小数据集:

  • 名称

  • 是否必须

  • 说明

“最小数据集”(MDS)是指通过收集最少的数据,较好地掌握一个研究对象所具有的特点或一件事情、一份工作所处的状态,其核心是针对被观察的对象建立起一套精简实用的数据指标。最小数据集的概念起源于美国的医疗领域。最小数据集的产生源于信息交换的需要,就好比上下级质量技术监督部门之间、企业与质量技术监督部门之间、质量技术监督部门与社会公众之间都存在着信息交换的需求。

一些文档里可能会加入字段的类型,但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化,大部分数据类型都是字符串。一些特殊的类型,例如枚举类型的字符串,可以在说明里描述。

另外:数据模型非常建议使用表格来表现

举个栗子

以上就是写好接口文档的方法的详细内容,更多文章请关注木庄网络博客

相关阅读 >>

web的接口管理工具

html中的meta设置方法

javascript中创建对象的方法有哪几种

关于html操作滚动条的方法

css如何让div居中?css实现div居中的方法

怎样用h5预览pdf格式的文档

html怎么去除字体下划线?去除字体下划线方法

pushstate、popstate操作url的方法

图片之间的缝隙解决方法

html中标签栏的几种实现方法

更多相关阅读请进入《方法》频道 >>




JavaScript 从入门到项目实践
书籍

JavaScript 从入门到项目实践

清华大学出版社

本书采取“基础知识→核心应用→核心技术→高级应用→行业应用→项目实践”的结构和“由浅入深,由深到精”的学习模式进行讲解。全书共35章,不仅介绍了HTML、CSS、对象、函数、事件等JavaScript语言的基础知识,而且深入介绍了jQuery、客户端、服务器端、数据存储等核心技术。



打赏

取消

感谢您的支持,我会继续努力的!

扫码支持
扫码打赏,您说多少就多少

打开支付宝扫一扫,即可进行扫码打赏哦

分享从这里开始,精彩与您同在

评论

管理员已关闭评论功能...