api接口稳文档（稳定的api接口）

本篇文章给大家谈谈api接口稳文档，以及稳定的api接口对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享api接口稳文档的知识，其中也会对稳定的api接口进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、什么是接口文档？
• 2、怎么写api接口
• 3、免费API接口的试用开发文档有吗
• 4、Restful接口文档规范

什么是接口文档？

接口文档又称为API文档，一般是由开发人员所编写的，用来描述系统所提供接口信息的文档。 大家都根据这个接口文档进行开发，并需要一直维护和遵守。
如果想系统的学习接口测试相关的技术，可以了解一下黑马程序员的软件测试课程，里面讲的非常详细。

怎么写api接口

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

推荐使用的是docway 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

一、请求参数

1. 请求方法

GET

用于获取数据

POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

DELETE

用于删除数据

其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

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

3. HTTP Header

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

常用的content-type：

application/x-www-form-urlencoded

请求参数使用“”符号连接。

application/json

内容为json格式

application/xml

内容为xml格式

multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

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

示例：

二、响应参数

1. 响应 HTTP Body

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

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

三、接口说明

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

四、示例

上个示例（重点都用红笔圈出来，记牢了）：

五、接口工具

推荐使用的是http://docway.net（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

免费API接口的试用开发文档有吗

Api接口就好比一个媒介工具api接口稳文档，比如买东西api接口稳文档的时候我们要计算价格，可以用算盘、计算器、手机或者电脑进行计算得出结果。接口与其类似，当api接口稳文档你需要用到这个功能时就可以调用。
Api接口可以应用于pc端、app、软件等，除api接口稳文档了接口一般会有Api接口文档说明来帮助开发者使用。
下面来分享一下免费的api接口以及文档说明：
1. 邮编查询：
接口地址：http://v.juhe.cn/postcode/query
返回格式：json/xml
请求方式：http get/post
请求示例：http://v.juhe.cn/postcode/query?postcode=215001key=申请的KEY
接口备注：通过邮编查询对应的地名
请求参数说明：
名称 类型 必填 说明
postcode 是 string 邮编，如：215001
key 是 string 应用APPKEY(应用详细页查询)
page 否 int 页数，默认1
pagesize 否 int 每页返回，默认:20,最大不超过50
dtype 否 string 返回数据的格式,xml或json，默认json
返回参数说明：
名称 类型 说明
error_code int 返回码
reason string 返回说明
JSON返回示例：
{
"reason": "successed",
"result": {
"list": [
{
"PostNumber": "215001",
"Province": "江苏省",
"City": "苏州市",
"District": "平江区",
"Address": "廖家巷新光里"
},
{
"PostNumber": "215001",
"Province": "江苏省",
"City": "苏州市",
"District": "平江区",
"Address": "龙兴桥顺德里"
}
],
"totalcount": 352,
"totalpage": 176,
"currentpage": 1,
"pagesize": "2"
},
"error_code": 0
}
2. 手机号码归属地:
接口地址：http://apis.juhe.cn/mobile/get
返回格式：json/xml
请求方式：get
请求示例：http://apis.juhe.cn/mobile/get?phone=13429667914key=您申请的KEY
请求参数说明：
名称 类型 必填 说明
phone 是 int 需要查询的手机号码或手机号码前7位
key 是 string 应用APPKEY(应用详细页查询)
dtype 否 string 返回数据的格式,xml或json，默认json
返回参数说明：
名称 类型 说明
error_code int 返回码
reason string 返回说明
result string 返回结果集
province string 省份
city string 城市，(北京、上海、重庆、天津直辖市可能为空)
areacode string 区号，(部分记录可能为空)
zip string 邮编，(部分记录可能为空)
company string 运营商
JSON返回示例：
{
"resultcode":"200",
"reason":"Return Successd!",
"result":{
"province":"浙江",
"city":"杭州",
"areacode":"0571",
"zip":"310000",
"company":"中国移动",
"card":""
}
}
XML返回示例：
<?xml version="1.0" encoding="utf-8" ?
- <root
<resultcode200</resultcode
<reasonReturn Successd!</reason
- <result
<province浙江</province
<city杭州</city
<areacode0571</areacode
<zip310000</zip
<company中国移动</company
<card</card
</result
</root
3. 影视影讯检索：
接口地址：http://op.juhe.cn/onebox/movie/video
返回格式：json/xml
请求方式：http get/post
请求事例http://op.juhe.cn/onebox/movie/video?key=APPKEYq=%E5%BA%B7%E7%86%99%E7%8E%8B%E6%9C%9D
接口备注：电影：q=心花路放；电视剧：q=继承者们；动漫：q=柯南
请求参数说明：
名称 类型 必填 说明
key 是 string 应用APPKEY(应用详细页查询)
dtype 否 string 返回数据的格式,xml或json，默认json
q 是 string 影视搜索名称
返回参数说明：
名称 类型 说明
error_code int 返回码
reason string 返回说明
JSON返回示例：
{
"reason": "查询成功",
"result": {
"title": "闪电侠第一季",
"tag": "科幻 / 动作",
"act": "格兰特·古斯汀 埃涅·赫德森 汤姆·卡瓦纳夫",
"year": "2014",
"rating": null,
"area": "美国",
"dir": "大卫·努特尔",
"desc": "《闪电侠》精彩看点：二次元超级英雄再登电视荧屏，《闪电侠》无缝对接《绿箭侠》闪耀登场。《闪电侠》剧情梗概：《闪电侠》的漫画连载开始于1940年，讲述api接口稳文档了一名拥有超级速度的学生的故事。50年代起，这个角色则被重新诠释，成为了巴里·艾伦，一名为警署工作的科学家，使用他的超级速度来对抗超级反派们。",
"cover": "http://i.gtimg.cn/qqlive/img/jpgcache/files/qqvideo/0/0l01jm9yobh4xo4.jpg",
"vdo_status": "play",
"playlinks": {
"youku": "http://v.youku.com/v_show/id_XODQ1NTAzNDE2.html?tpa=dW5pb25faWQ9MTAyMjEzXzEwMDAwNl8wMV8wMQ",
"qq": "http://v.qq.com/cover/0/0l01jm9yobh4xo4/g0015dn2fw1.html",
"leshi": "http://www.letv.com/ptv/vplay/21416940.html",
"pptv": "http://v.pptv.com/show/2uhW1T2jE1G0Mr4.html",
"sohu": "http://tv.sohu.com/20141210/n406824703.shtml?txid=4e4df35dda9d8ed32c874b1ad590ef59"
},
"video_rec": [
{
"detail_url": "http://kan.com/tv/PrVtaX7kRzXsMn.html",
"cover": "http://p2.qhimg.com/t01f969930fae67d1ec.jpg",
"title": "神盾局特工 第2季"
},
{
"detail_url": "http://kan.com/tv/Q4RvaqOoRmDuMX.html",
"cover": "http://p6.qhimg.com/t0160a8a6f5b768034a.jpg",
"title": "遗失的世界"
},
{
"detail_url": "http://kan.com/tv/Q4Frc3GoRmbuMX.html",
"cover": "http://p7.qhimg.com/t01513514907831e055.jpg",
"title": "浩劫余生 第一季"
},
{
"detail_url": "http://kan.com/tv/QrFob33oRGboMX.html",
"cover": "http://p6.qhimg.com/d/_hao360/video/img200909_18_145544738.jpg",
"title": "新绿野仙踪之铁皮人"
},
{
"detail_url": "http://kan.com/tv/QrRtbaOpRz4nOH.html",
"cover": "http://p1.qhimg.com/t01d2996b3305923b91.jpg",
"title": "陨落星辰第三季"
}
],
"act_s": [
{
"name": "格兰特·古斯汀",
"url": "http://baike.so.com/doc/2041872.html",
"image": "http://p3.qhimg.com/dmsmty/120_110_100/t019f2fb2f92c6cb2cf.jpg"
},
{
"name": "埃涅·赫德森",
"url": "http://baike.so.com/doc/3938849.html",
"image": "http://p2.qhimg.com/dmsmty/120_110_100/t0169332727e692e9fa.jpg"
},
{
"name": "汤姆·卡瓦纳夫",
"url": "http://baike.so.com/doc/7521211.html",
"image": "http://p0.qhimg.com/dmsmty/120_110_100/t01d271d8c090330ae2.jpg"
}
]
},
"error_code": 0
}
4. 商品比价查询：
API调用地址：
http://sapi.manmanbuy.com/Search.aspx?AppKey=申请appkeyKey=搜索关键词Class=分类IDBrand=品牌IDSite=商城IDPriceMin=最低价PriceMax=最高价PageNum=页号PageSize=每页商品数OrderBy=排序方式ZiYing=是否自营ExtraParameter=扩展参数
调用示例
http://sapi.manmanbuy.com/Search.aspx?AppKey=123456Key=iphoneClass=0Brand=0Site=0PriceMin=0PriceMax=0PageNum=1PageSize=30OrderBy=scoreZiYing=falseExtraParameter=0
返回结果示例(以iphone为例，显示前2条商品信息)：
{"State":1000,"SearchItemsCount":101520,"SearchCount":5109,"ClassList":"57|1074|手机,893|29964|iPhone 配件,892|19512|手机保护套,910|11169|苹果配件, 890|8766|手机贴膜 ,894|6201|其它配件,900|3189|移动电源,889|2067|手机充电器,898|1923|电池/充电器,101|1518|耳机,888|1290|手机电池, 100|1074|蓝牙耳机","BrandList":"155|47184|苹果,0|40476|,634|2166|洛克,6|1134|三星,622|1023|倍思,261|564|品胜,652|558|SGP, 639|537|ESR,623|474|邦克仕,10|423|飞利浦,604|330|摩米士,664|291|优胜仕","SiteList":"1|66732|京东商城,4|8478|亚马逊,3|7917| 当当,13|4821|1号店,6|4605|苏宁易购,8|4149|国美在线,11|3882|易迅网,9|360|新蛋网,161|168|飞牛网,185|147|顺电网,124|123|高鸿商城, 123|69|华强北","SearchResultList":[{"spname":"苹果(Apple)iPhone 6 (A1586) 16GB 金色 移动联通电信4G手机", "sppic":"http://img14.360buyimg.com/n7/jfs/t277/193/1005339798/768456/29136988/542d0798N19d42ce3.jpg", "spurl":"http://item.jd.com/1217499.html","spprice":"5188.00","className":"手机","brandName":"苹果","siteName":"京东商城", "commentUrl":"http://item.jd.com/1217499.html#comments-list","commentCount":"8773", "TitleHighLighter":"苹果(Apple)iPhone 6 (A1586) 16GB 金色 移动联通电信4G手机","ziying":"1","siteid":"1","id":"98084930"}, {"spname":"苹果(Apple)iPhone 6 Plus (A1524) 16GB 金色 移动联通电信4G手机", "sppic":"http://img14.360buyimg.com/n7/jfs/t346/302/1010969394/231745/50f20b36/542d0e26N894372e9.jpg", "spurl":"http://item.jd.com/1217524.html","spprice":"5988.00","className":"手机","brandName":"苹果","siteName":"京东商城", "commentUrl":"http://item.jd.com/1217524.html#comments-list","commentCount":"10288", "TitleHighLighter":"苹果(Apple)iPhone 6 Plus (A1524) 16GB 金色 移动联通电信4G手机","ziying":"1","siteid":"1","id":"98084932"}]}

Restful接口文档规范

基于目前的大前端时代，对于常年负责后台开发的我来说， 最重要的就是提供稳定的接口和文档。便于小伙伴们进行业务对接。

当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。
API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。
应该尽量将API部署在专用域名之下： https://api.example.com

如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下： https://www.example.com/api
https://api.example.com/v{n}

1、应该将API的版本号放入URL。

2、采用多版本并存，增量发布的方式。

3、n代表版本号，分为整型和浮点型

整型： 大功能版本， 如v1、v2、v3 ...

浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...

4、对于一个 API 或服务，应在生产中最多保留 3 个最详细的版本
路径又称"终点"（end point），表示API的具体网址。

1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。

【所用的名词往往与数据库的表格名对应】

2、数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

例子: https://api.example.com/v1/products

https://api.example.com/v1/users

https://api.example.com/v1/employees
GET（SELECT）： 从服务器取出资源（一项或多项）。

POST（CREATE）： 在服务器新建一个资源。

PUT（UPDATE）： 在服务器更新资源（客户端提供改变后的完整资源）。

DELETE（DELETE）： 从服务器删除资源。

例子：

GET /v1/products 获取所有商品

GET /v1/products/ID 获取某个指定商品的信息

POST /v1/products 新建一个商品

PUT /v1/products/ID 更新某个指定商品的信息

DELETE /v1/products/ID 删除某个商品,更合理的设计详见【9、非RESTful API的需求】

GET /v1/products/ID/purchases 列出某个指定商品的所有投资者

GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息
若记录数量很多，服务器不可能返回全部记录给用户。

API应该提供分页参数及其它筛选参数，过滤返回结果。

/v1/products?page=1pageSize=20 指定第几页，以及每页的记录数。

/v1/products?sortBy=nameℴ=asc 指定返回结果按照哪个属性排序，以及排序顺序。
传入参数分为4种类型：

1、cookie： 一般用于OAuth认证

2、request header： 一般用于OAuth认证

3、请求body数据：

4、地址栏参数：

1）restful 地址栏参数 /v1/products/ID ID为产品编号，获取产品编号为ID的信息

2）get方式的查询字段 见【六、过滤信息】
response：

----------------------------------------

{

status: 200, // 详见【status】

data: {

code: 1, // 详见【code】

data: {} || [], // 数据

message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】

sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行

... // 其它参数，如 total【总记录数】等

},

msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】

sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行

}

----------------------------------------

【status】:

200: OK 400: Bad Request 500：Internal Server Error

401：Unauthorized

403：Forbidden

404：Not Found

【code】:

1: 获取数据成功 | 操作成功 0：获取数据失败 | 操作失败
1、实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的。

2、需要有一些api突破restful规范原则。

3、特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。

1)、删除单个 | 批量删除 ： DELETE /v1/product body参数{ids：[]}

2)、页面级API : 把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
1、前端需要哪些字段，API接口应该返回哪些字段，字段不多也不少。

2、更新功能尽量做到：初次返回的原始数据参数与提交更新的数据参数结构一致。

3、时间参数，尽量以一致格式的字符串传递， 如：

‘2019-01’ | ‘2019/01’

‘2019-01-01’ | ‘2019/01/01’

‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
1、尽量采用自动化接口文档，可以做到在线测试，同步更新。

2、应包含：接口BASE地址、接口版本、接口模块分类等。

3、每个接口应包含：

接口地址：不包含接口BASE地址。

请求方式: get、post、put、delete等。

请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。

相应参数：类型、中文描述。 关于api接口稳文档和稳定的api接口的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 api接口稳文档的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于稳定的api接口、api接口稳文档的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。