api设计接口文档（api接口的简单编写方式）

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

本文目录一览：

• 1、API接口入门（一）：读懂API接口文档
• 2、怎么写api接口
• 3、使用 API Blueprint 来编写 API 接口文档

API接口入门（一）：读懂API接口文档

本文目录：

API接口是什么？

为什么我们需要API接口？

API接口的核心

一、API接口是什么？

我们来以一个常见的数学公式理解API，比如y=x+2，当x=2的时候，y=4，对么？

那此时，我们把y=x+2称为接口，x=2称为参数，y=4称为返回结果，那这个接口的功能就是能把我们输入的数加上2（注意：这里你可以发现接口自身是带有逻辑的）。

类比地，我们来理解一个常见的场景，比如现在有一个可以把经纬度转化为城市的接口，那当我输入经度是55°，纬度是88°的时候，接口通过自己的逻辑运算，返回结果告诉我：杭州市。

这样你就可以清晰地了解百度百科的官方解释了，接口就是预先定义的函数逻辑，他是供其他系统请求，然后返回结果的一个东西。

二、为什么我们需要API接口？

背景：我们的业务系统涉及多方多面，如果要一个公司或者一个系统把所有业务都做完，那未免工作量太大了吧？并且如果其他系统或公司有更好的运算逻辑，那我们在设计功能的时候可以考虑利用接口进行开发。

核心需求：利用现有接口可以降低开发成本，缩短开发成本。

举个例子：比如我是打车的APP，现在我需要在我的页面上展现地图的功能，对于我司而言，新做地图功能未免成本过高，那我们可以在高德开放平台或者百度地图的开放平台，找到地图API，这样的话我们只需要购买高德的服务，部署调用高德地图API，这样就可以快速在我们页面上线地图功能了。

三、API接口的核心

对于小白而言，初看API文档可能是一头雾水的——从哪里看，怎么看，看什么是摆在面前的问题。

其实对于产品经理而言，我们应该更关注这个公司可以提供什么样的API接口服务，比如我知道高德可以提供地图API，规划路线的API，这样的话在我们设计功能和工作中就可以想到调用他们的服务或者参考。

所以产品小白们看不懂也不用过于担心，未来工作中你也会更深入了解清楚，因为看懂并不复杂，以下是API接口的核心点，所有的说明文档离不开这5个核心点。

以下说明均以微信开放平台为例说明，文末有各开放平台的地址，大家有空可以去学习。好了，事不宜迟，现在我们来建立一个场景。

我们现在有一个APP，需要用户在购买的时候调起微信支付的API，完成购买。请各位自动进入这个场景，把自己当作一位产品经理。

1. 接口地址

现在Now，用户点击付款，我们需要告诉微信，我们要调起你们的收银台啦！但，去哪里告诉呢？这就需要接口地址了，也就相当于向微信的这条链接传输指定的数据。

一个链接地址不是我们理解的一个页面，你可以理解是一个电话号码，小白们要改变这个观念。

此时我们可以看到接口文档告诉我们链接是如下这条，那我们现在已经拨通微信的电话了。

2. 请求参数（报文）

我们现在需要告诉微信，你想调用收银台对吧。那我们需要写下来，此时生成的叫做报文，也就是你想告诉这个接口的内容是什么？相当于前文函数的输入x=2。

一般来说，报文的格式和内容都是按接口文档规定的。如下文就是微信开放平台对调起收银台的报文要求。

我们先来看前2个参数，你现在跟微信在对话，是不是应该先告诉微信，你是谁？这里微信的文档告诉你应该要用应用ID+商户号来确定你的身份，什么意思呢？

比如你是A商户，下面有a，b，c三个APP，所以微信要知道你是哪个商家，下面的哪个APP要用收银台。这是非常重要的，微信后面要把收到的钱打到对应的账户以及统计数据等。

那我们就在报文里面写下这两句话：

<appidwx2421b1c4370ec43b</appid（我的应用ID是wx2421…….）

<mch_id10000100</mch_id（我的商户号是10000…….）

好了，现在微信知道你是谁了，那你要告诉微信，你需要微信支付帮你收多少钱对吧？这里定义了货币类型和总金额，也就是收什么货币，收多少钱。

这里你看，货币类型的必填写了否，也就是说你也可以不告诉微信支付货币类型是什么，因为他在后面备注了默认是人民币。

好的，那我们写下两段报文

<free_typeCNY</ free_type （我要收人民币）

<total_fee1</total_fee（我要收1元）

好了，现在微信知道你是谁，也知道要收多少钱了，那接下来微信支付要把收钱结果告诉你呀，因为你得知道用户是成功支付了才能继续发货，服务啊等等的。所以这里我们用到通知地址，就是告诉微信，等下完事了他去哪里告诉你支付结果。那我们把地址写好：

<notify_urlhttp://wxpay.wxutil.com/pub_v2/pay/notify.v2.php</notify_url

3. 返回结果

刚刚微信支付已经去收款了，现在他要在我们留下的通知地址中，告诉我们结果了。结果无非是两种：成功收款？收款不成功？

（1）成功

很顺利，现在用户成功付钱了，并且微信也把成功的消息告诉我们了，并且他还把用户支付的一些信息也告诉我们。

那这里就是微信支付成功收款后告诉我们的信息。

应用APPID，商户号：告诉你我成功扣款的是哪家商户的哪个APPID的交易。

业务结果：成功或失败

（2）失败

在产品设计的时候，我们往往很关注失败的情况，当收款失败的时候，微信同时会告诉你失败的原因，如下图很好理解，失败的原因有很多很多种，我们在设计的时候往往要分析每种失败的原因，为每个失败的原因设计页面和用户提示，以确保用户能理解。

以上就是API接口基本运作模式的理解，下面我将继续更新API接口的一些更为深入和细节的关键元素，如请求方式/签名/加解密等等。

可供参考的开放平台网站

微信支付：https://pay.weixin.qq.com/wiki/doc/api/index.html

高德平台开放平台：https://lbs.amap.com/

怎么写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 Blueprint 来编写 API 接口文档

API Blueprint 用来编写API文档的一种标记语言，类似于Markdown，具体的语法规则可以在 API Blueprint documentation 查看，文档里面还有一个简短的 API Blueprint tutorial 建议先仔细阅读一下这个教程。

使用 API Blueprint 文档，配合一些开源的工具可以把接口文档渲染成 html 再搭配一个静态服务器，就可以很方便的共享给同事。

相对于 word 这种富文本格式的文档来说， API Blueprint 是纯文本，这样可以很方便的使用版本控制工具 Git 来控制版本。

另外，配合一些工具，可以直接生成一个 mock data 数据，这样只要和后端的同学约定好接口格式，那么前端再开发的时候可以使用 mock data 数据来做测试，等到后端写好接口之后再做联调就可以了。

API Blueprint 社区提供了一些文本编辑器的插件，可以识别 API Blueprint 语法支持语法高亮。

使用 apiblueprint 编写好文档使用，可以使用开源社区提供的一个工具 aglio 来把接口文档渲染成 html 文件， aglio 还会启动一个静态服务器，这样就可以在浏览器里面查看渲染好的文档了。

aglio 的使用教程，可以直接查看官方开发仓库的 readme 文档。另外，这里也有一份资料 使用API-Blueprint 编写 API 文档 可以参考。

关于api设计接口文档和api接口的简单编写方式的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 api设计接口文档的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于api接口的简单编写方式、api设计接口文档的信息别忘了在本站进行查找喔。

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