api接口文档说明书（api接口怎么编写）

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

本文目录一览：

• 1、怎么写api接口
• 2、Baidu云盘API接口的使用使用说明
• 3、免费API接口的试用开发文档有吗
• 4、API是什么意思？API文档又是什么意思？
• 5、什么是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，支持团队项目管理。

Baidu云盘API接口的使用使用说明

这几天很有兴致的学习了百度云盘文件API接口的使用 初步是想做一个在线android应用 应用中的文档是存放在百度云盘的 主要是分一下几个步骤     注册百度账号    登录百度开发者中心    创建移动应用 获取对应的（API Key Secret Key）    开通pcs API权限    获取ACCESS_token（认证编码）    开发应用 注意     开通移动应用 获取key    获取token的时候我使用的安卓获取的方式    通过我写对应api的例子我发现 其实就两种情况 一种是get方式提交数据 另外一种是post方式提交数据    get方式提交数据 我们用获取云盘的信息为例     获取云盘信息前我们要知道 我们要准备好什么数据 请求参数     url: 标明我们要访问的网址路径 值固定问     method:标明我们是请求云盘信息 值固定为 info     acceess_token:准入标识 值是我们自己申请的 接收返回参数     quota:云盘总容量    used:云盘使用容量    request_id:该请求的表示 没啥用    返回的一个json串如下格式 { quota : used : request_id : }    我在做的时候你使用Gson工具将json串转换到对应的entity类中了 代码如下     [] /**    * @param URLConnection conn通过get方式获取StringBuffer    * @return    */    private StringBuffer getJsonString（URLConnection conn） {    InputStreamReader isr = null;    BufferedReader br = null;    StringBuffer *** = null;    try {    isr = new InputStreamReader（conn getInputStream（） gb ）     br = new BufferedReader（isr）     String line = null;    *** = new StringBuffer（）     while （（line = br readLine（）） != null） {    *** append（line）     *** append（ \r\n ）     }    } catch （UnsupportedEncodingException e） {    e printStackTrace（）     } catch （IOException e） {    e printStackTrace（）     }finally{    try {    if（isr!=null）    isr close（）     } catch （IOException e） {    System out println（ 流关闭是异常 ）     e printStackTrace（）     }    }    return *** ;    }    /**    * @return    * @throws Exception    * 获取云空间的信息    */    public CloudInfo getCloudInfo（） throws Exception {    URL u = new URL（ ?method=infoaccess_token=你申请的token的值 ;    URLConnection conn = u openConnection（） // 打开网页链接    // 获取用户云盘信息    String cloudJson = this getJsonString（conn） toString（）

// 解析成对象 下面有这个实体对象的类    Gson gson = new Gson（）     CloudInfo cloudInfo = gson fromJson（cloudJson CloudInfo class）     System out println（ 云盘信息 +cloudInfo）     return cloudInfo;    }    /**    * @param URLConnection conn通过get方式获取StringBuffer    * @return    */    private StringBuffer getJsonString（URLConnection conn） {    InputStreamReader isr = null;    BufferedReader br = null;    StringBuffer *** = null;    try {    isr = new InputStreamReader（conn getInputStream（） gb ）     br = new BufferedReader（isr）     String line = null;    *** = new StringBuffer（）     while （（line = br readLine（）） != null） {    *** append（line）     *** append（ \r\n ）     }    } catch （UnsupportedEncodingException e） {    e printStackTrace（）     } catch （IOException e） {    e printStackTrace（）     }finally{    try {    if（isr!=null）    isr close（）     } catch （IOException e） {    System out println（ 流关闭是异常 ）     e printStackTrace（）     }    }    return *** ;    }    /**    * @return    * @throws Exception    * 获取云空间的信息    */    public CloudInfo getCloudInfo（） throws Exception {    URL u = new URL（ ?method=infoaccess_token=你申请的token的值 ;    URLConnection conn = u openConnection（） // 打开网页链接    // 获取用户云盘信息    String cloudJson = this getJsonString（conn） toString（）     // 解析成对象 下面有这个实体对象的类    Gson gson = new Gson（）     CloudInfo cloudInfo = gson fromJson（cloudJson CloudInfo class）     System out println（ 云盘信息 +cloudInfo）     return cloudInfo;    }    [] package entity;    import java lang reflect Type;    /**    * @author ydcun 获取云空间的信息 例如     * { quota : 空间配额 单位为字节    * used : 已使用空间大小 单位为字节     * request_id : }    */    public class CloudInfo{    private Double quota;    private Double used;    private Double request_id;    /**    * @return the quota 空间配额 单位为字节    */    public Double getQuota（） {    return quota;    }    /**    * @param quota the quota to set 空间配额 单位为字节    */    public void setQuota（Double quota） {    this quota = quota;    }    /**    * @return the used 已使用空间大小 单位为字节    */    public Double getused（） {    return used;    }    /**    * @param used the used to set 已使用空间大小 单位为字节    */    public void setused（Double used） {    this used = used;    }    /**    * @return the request_id    */    public Double getRequest_id（） {    return request_id;    }    /**    * @param request_id the request_id to set    */    public void setRequest_id（Double request_id） {    this request_id = request_id;    }    @Override    public String toString（） {    return new StringBuffer（） append（ 空间容量 ） append（this getQuota（）/ / ） append（ M; 已用 ） append（this getused（）/ / ） append（ M; ） toString（）     }    }    package entity;    import java lang reflect Type;    /**    * @author ydcun 获取云空间的信息 例如     * { quota : 空间配额 单位为字节    * used : 已使用空间大小 单位为字节     * request_id : }    */    public class CloudInfo{    private Double quota;    private Double used;    private Double request_id;    /**    * @return the quota 空间配额 单位为字节    */    public Double getQuota（） {    return quota;    }    /**    * @param quota the quota to set 空间配额 单位为字节    */    public void setQuota（Double quota） {    this quota = quota;    }    /**    * @return the used 已使用空间大小 单位为字节    */    public Double getused（） {    return used;    }    /**    * @param used the used to set 已使用空间大小 单位为字节    */    public void setused（Double used） {    this used = used;    }    /**    * @return the request_id    */    public Double getRequest_id（） {    return request_id;    }    /**    * @param request_id the request_id to set    */    public void setRequest_id（Double request_id） {    this request_id = request_id;    }    @Override    public String toString（） {    return new StringBuffer（） append（ 空间容量 ） append（this getQuota（）/ / ） append（ M; 已用 ） append（this getused（）/ / ） append（ M; ） toString（）     }    }

lishixinzhi/Article/program/Java/hx/201311/27162

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

Api接口就好比一个媒介工具，比如买东西的时候我们要计算价格，可以用算盘、计算器、手机或者电脑进行计算得出结果。接口与其类似，当你需要用到这个功能时就可以调用。
Api接口可以应用于pc端、app、软件等，除了接口一般会有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年，讲述了一名拥有超级速度的学生的故事。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"}]}

API是什么意思？API文档又是什么意思？

API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。

API文档是一个技术内容交付文件，包含如何有效地使用和集成api的说明。它是一个简明的参考手册，包含了使用API所需的所有信息，详细介绍了函数、类、返回类型、参数等，并有教程是示例支撑。

API文档传统上是使用常规内容创建和维护工具和文本编辑器完成的。API描述格式如OpenAPI /Swagger规范具有自动文档编制流程，它使得团队更容易生成和维护API文档。

扩展资料：

Windows API

API函数包含在Windows系统目录下的动态连接库文件中。Windows API是一套用来控制Windows的各个部件的外观和行为的预先定义的Windows函数。用户的每个动作都会引发一个或几个函数的运行以告诉Windows发生了什么。

这在某种程度上很像Windows的天然代码。而其他的语言只是提供一种能自动而且更容易的访问API的方法。当你点击窗体上的一个按钮时，Windows会发送一个消息给窗体，VB获取这个调用并经过分析后生成一个特定事件。

更易理解来说：Windows系统除了协调应用程序的执行、内存的分配、系统资源的管理外，同时他也是一个很大的服务中心。

调用这个服务中心的各种服务(每一种服务就是一个函数)可以帮助应用程序达到开启视窗、描绘图形和使用周边设备等目的，由于这些函数服务的对象是应用程序，所以称之为Application Programming Interface，简称API 函数。

WIN32 API也就是MicrosoftWindows 32位平台的应用程序编程接口。凡是在 Windows工作环境底下执行的应用程序，都可以调用Windows API。

linux API

在linux中，用户编程接口API遵循了UNIX中最流行的应用编程界面标准---POSIX标准。POSIX标准是由IEEE和ISO/IEC共同开发的标准系统。

该标准基于当时现有的UNIX实践和经验，描述了操作系统的系统调用编程接口API，用于保证应用程序可以在源程序一级上在多种操作系统上移植运行。这些系统调用编程接口主要是通过C库（LIBC）来实现的。

参考资料：百度百科-api

什么是API接口？主要作用是什么？

API(Application
Programming
Interface,应用程序编程接口)是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。API除了有应用“应用程序接口”的意思外，还特指
API的说明文档，也称为帮助文档。另外，也是美国石油协会、空气污染指数、医药、空中位置指示器的英文简称。
作为国内领先api卡类接口提供商（70卡世界），不仅支持现代电子商务活动中网银支付在线交易最典型和最成熟的支付方式，它功能齐全、覆盖范围广，货币流通顺畅，使用网银支付已是在线交易中最普遍最实用的一种方式。目前，70卡世界开拓出卡类支付通道，开通了最安全最广泛的交易快捷通道，有了网银支付这一功能，我们的在线交易就得到全面完善，从而就给人们带来多种多样的在线交易方式。已覆盖的卡类通道包括：神州行(地方)充值卡、神州行(全国)充值卡、
中国电信充值付费卡、联通全国充值卡、完美一卡通、骏网一卡通、搜狐一卡通、网易一卡通、
盛大一卡通、征途一卡通、久游一卡通、
QB卡、纵游一卡通、
蓝港一卡通等卡种，力求为70商户提供最专业最全的卡类支付通道。 关于api接口文档说明书和api接口怎么编写的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 api接口文档说明书的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于api接口怎么编写、api接口文档说明书的信息别忘了在本站进行查找喔。

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