您当前的位置:首页 > 新闻 > 科技

怎么写接口文档

时间:2020-03-15 12:24:16  来源:  作者:

一些刚开始写接口文档的服务端同学,很容易按着代码的思路去编写接口文档,这让客户端同学或者是服务对接方技术人员经常吐槽,看不懂接口文档。这篇文章提供一个常规接口文档的编写方法,给大家参考。

一、请求参数

  1. 请求方法
  • GET 用于获取数据
  • POST 用于更新数据
  • PUT 用于新增数据
  • DELETE用于删除数据
  • 其他 其他的请求方法在一般的接口中很少使用。如:PATCH HEAD OPTIONS
  1. URL

url表示了接口的请求路径。路径中可以包含参数,称为地址参数,如/user/{id},其中id作为一个参数。

  1. HTTP Header

HTTP Header用于此次请求的基础信息,在接口文档中以K-V方式展示,其中Content-Type则是一个非常必要的header,它描述的请求体的数据类型。

常用的content-type:

  • Application/x-www-form-urlencoded
  • application/json
  • application/xml
  • multipart/form-data
  1. HTTP Body

描述http body,依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例:

 

怎么写接口文档

 

 

二、响应参数

  1. 响应 HTTP Body

响应body同请求body一样,需要描述请清除数据的类型。

另外,如果服务会根据不同的http status code 返回不同的数据结构, 也需要针对不同的http status code对内容进行描述。

 

怎么写接口文档

 

 

三、接口说明

说明接口的应用场景,特别的注意点,比如,接口是否幂等、处理是同步方式还是异步方式等。

笔者平时使用的是 http://www.docway.net(以前叫小幺鸡) 这个网站写接口文档,方便保存和共享。

四、示例

上个示例(重点都用红笔圈出来,记牢了):

 

怎么写接口文档


Tags:接口文档   点击:()  评论:()
声明:本站部分内容及图片来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系(Email:2595517585@qq.com),我们将及时更正、删除,谢谢。
▌相关推荐
前言前后端分离开发模式中,api文档是最好的沟通方式。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。 源码传送门: https://gitee.com/huoqstudy/xiliu-...【详细内容】
2021-09-08  Tags: 接口文档  点击:(65)  评论:(0)  加入收藏
一些刚开始写接口文档的服务端同学,很容易按着代码的思路去编写接口文档,这让客户端同学或者是服务对接方技术人员经常吐槽,看不懂接口文档。这篇文章提供一个常规接口文档的编...【详细内容】
2020-03-15  Tags: 接口文档  点击:(87)  评论:(0)  加入收藏
前言作为一个以前后端分离为模式开发小组,我们每隔一段时间都进行这样一个场景:前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试...【详细内容】
2019-12-25  Tags: 接口文档  点击:(129)  评论:(0)  加入收藏
日常项目开发的过程中,接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记...【详细内容】
2019-10-23  Tags: 接口文档  点击:(201)  评论:(0)  加入收藏
▌简易百科推荐
非法购买公民信息、开发人脸认证规避技术……今年年初,广东省公安厅网安部门侦破全国首例破解“青少年防沉迷系统”的新型网络犯罪案件,抓获犯罪嫌疑人13名,查处非...【详细内容】
2021-12-28    人民日报客户端  Tags:数据安全步   点击:(5)  评论:(0)  加入收藏
就在今天,腾讯方面宣布将在2022年1月31日下架企业QQ和营销QQ,其实这一消息的降临并不让笔者意外,因为早在今年的10月28日20点之后,企业QQ和营销QQ就被停止了续费服务。相信很多...【详细内容】
2021-12-27  科技探险家    Tags:企业QQ   点击:(21)  评论:(0)  加入收藏
日前,上海交通大学发布《全球电竞之都评价报告》,对全球15个致力于发展电竞之都的城市进行评价,上海作为中国城市电竞发展的排头兵,其拥有众多优质电竞企业及完整产业集群,因此排...【详细内容】
2021-12-27  经济日报    Tags:电竞   点击:(3)  评论:(0)  加入收藏
为优化网络氛围环境,微博又开始整顿用户信息了。本月月初,微博官方发布公告,要求昵称中带有如“二货”“SB”“瘪三”“娘炮”等明显低俗或侮辱性词汇的用户尽快修改,否则将面临...【详细内容】
2021-12-24  运了个营    Tags:微博   点击:(10)  评论:(0)  加入收藏
昨日谷歌宣布,自2022年12月19日开始停止对OnHub的软件支持,OnHub路由器仍将提供Wi-Fi信号,但用户无法用谷歌Home应用程序管理它。无法更新Wi-Fi网络设置、添加额外的Wifi设备或...【详细内容】
2021-12-22  雷峰网    Tags:Google OnHub   点击:(5)  评论:(0)  加入收藏
IT之家 12 月 20 日消息,百度网盘青春版 iOS 客户端今日晚间率先开启内测,安卓客户端将在稍后内测。使用苹果 iPhone 的IT之家小伙伴可以点此下载内测版,需要先下载 TestFlight...【详细内容】
2021-12-21  IT之家    Tags:百度网盘   点击:(10)  评论:(0)  加入收藏
对于拼车单,是接还是不接,不少网约车司机表示很矛盾。接吧,钱少事多,常常跑了个寂寞,不接吧,车多客少,挑三拣四没饭吃。 在平台大力推广拼车单之下,不少司机迫于生活压力,最终还是打...【详细内容】
2021-12-17  网约车情报分享    Tags:滴滴   点击:(9)  评论:(0)  加入收藏
蓝鲸TMT频道12月16日讯,据饿了么官方微信公众号,近日,在圆桌会上,蓝骑士与平台交流了配送安全问题。饿了么表示,线上将技术手段融入安全防护;线下将持续进行安全培训,并试点智能头...【详细内容】
2021-12-17    金融界  Tags:饿了么   点击:(24)  评论:(0)  加入收藏
开源最前线(ID:OpenSourceTop) 猿妹编译项目地址: https://github.com/restic/restic全球知名代码托管平台 GitHub 今天就重磅发布了今年的年度报告——《2021 年度 O...【详细内容】
2021-12-17  Python部落    Tags:   点击:(9)  评论:(0)  加入收藏
新京报快讯 据中国网络视听节目服务协会网站消息,12月15日,中国网络视听节目服务协会发布了《网络短视频内容审核标准细则》(2021)。中国网络视听节目服务协会组织有关短视频平...【详细内容】
2021-12-16    新京报  Tags:短视频   点击:(11)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条