提升用户体验的关键：跨境电商的支付成本分析
522
2023-01-10
在线api接口文档系统（在线api接口文档系统怎么用）
本篇文章给大家谈谈在线api接口文档系统，以及在线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/
其中不可避免的就是定制好接口文档，后端工程师要写好单元测试，推荐使用 chrome 的插件 postman 或 soapui或 jmeter，service 层的测试用例拿 junit 写。
但是这种情况对于接口文档管理很不方便，所以下面就罗列一些互联网公司常用的接口文档管理平台。
Swagger是一个大型的API开发者的工具框架，该框架提出了一个编写OpenAPI的规范（命名为OAS），并且Swagger可以跨整个API生命周期进行开发，从设计和文档到测试和部署。
Swagger框架三核心：
YApi部署流程介绍
YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。它可以帮助开发者轻松创建、发布、以及维护API。除此之外，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。特性:
难点：如果需要要执行自动化测试，需要编写脚本。
Eolinker是国内企业级IT研发管理解决方案服务品牌，在线API接口管理服务供应商，致力于满足各行业客户在不同应用环境中对研发管理全生命周期的个性化需求，提供API开发管理（AMS）、开发团队协作、自动化测试、网关（AGW）以及监控（AMT）等服务。
特性：
ShowDoc一个非常适合IT团队的在线API文档、技术文档工具。
随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供API，APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。
项目地址： https://www.showdoc.cc
DOClever是一个可视化接口管理工具 ,可以分析接口结构，校验接口正确性， 围绕接口定义文档，通过一系列自动化工具提升我们的协作效率。
特性：
DOClever官网： http://www.doclever.cn/controller/index/index.html
DOClever GitHub： https://github.com/sx1989827/DOClever
阿里妈妈前端团队出品的开源接口管理工具RAP第二代，RAP通过GUI工具帮助WEB工程师更高效的管理接口文档，同时通过分析接口结构自动生成Mock数据、校验真实接口的正确性，使接口文档成为开发流程中的强依赖。有了结构化的API数据，RAP可以做的更多，而我们可以避免更多重复劳动。基于RAML的接口定义、文档生成、Mock Server完成了定义和使用的分离，通过一套规范完成的接口定义，可以用不同的工具得到适应不同API管理系统的输出，有更多的可能性，同时保持了核心定义不变。RAP较之于RAML，前者更加集中，所有的定义、文档、mock都在同一个服务中完成，并且实时生效，方便快捷，如果只考虑方便易用，RAP是更好的选择，而RAML显得更加繁琐，更适合于公开的接口定义，方便在各个系统之间流转。
github源码地址： https://github.com/thx/rap2-delos
SwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用（官方demo）。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。
2.快速开始
创建项目 OnlineAPI来封装百度音乐服务(示例下载) ，通过API可以搜索、获取音乐的信息和播放连接。
我尽量删除一些我们demo中不会用到的一些文件，使其看上去比较简洁。
WebAPI 安装 Swashbuckle
Install-Package Swashbuckle
代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的，生成 SwaggerUI，JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相关展示行为的。如图：
将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在当前类中添加一个方法
/// <summary
/// </summary
/// <param name="name"</param
/// <returns</returns
protected static string GetXmlCommentsPath(string name)
{
return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}
紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”，编译过程中生成类库的注释文件
添加百度音乐 3个API
访问 lt;youhost/swagger/ui/index,最终显示效果
我们通过API 测试API 是否成功运行
3.添加自定义HTTP Header
在开发移动端 API时常常需要验证权限，验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可
首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
public class HttpHeaderFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry
schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null) operation.parameters = new
List<Parameter();
var filterPipeline =
apiDescription.ActionDescriptor.GetFilterPipeline();
//判断是否添加权限过滤器
var isAuthorized = filterPipeline.Select(filterInfo =
filterInfo.Instance).Any(filter = filter is IAuthorizationFilter);
//判断是否允许匿名方法
var allowAnonymous =
apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute().Any();
if (isAuthorized !allowAnonymous)
{
operation.parameters.Add(new Parameter
{
name = "access-key",
@in = "header",
description = "用户访问Key",
required = false,
type = "string"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<HttpHeaderFilter();
添加Web权限过滤器
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class AccessKeyAttribute : AuthorizeAttribute
{
/// <summary
/// 权限验证
/// </summary
/// <param name="actionContext"</param
/// <returns</returns
protected override bool IsAuthorized(HttpActionContext actionContext)
{
var request = actionContext.Request;
if (request.Headers.Contains("access-key"))
{
var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
//TODO 验证Key
return accessKey == "123456789";
}
return false;
}
/// <summary
/// 处理未授权的请求
/// </summary
/// <param name="actionContext"</param
protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)
{
var content = JsonConvert.SerializeObject(new {State = HttpStatusCode.Unauthorized});
actionContext.Response = new HttpResponseMessage
{
Content = new StringContent(content, Encoding.UTF8, "application/json"),
StatusCode = HttpStatusCode.Unauthorized
};
}
}
}
在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]
最终显示效果
4.显示上传文件参数
SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似，只是我们通过特殊的设置来标示API具有上传文件的功能
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class UploadFilter : IOperationFilter
{
/// <summary
/// 文件上传
/// </summary
/// <param name="operation"</param
/// <param name="schemaRegistry"</param
/// <param name="apiDescription"</param
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (!string.IsNullOrWhiteSpace(operation.summary) operation.summary.Contains("upload"))
{
operation.consumes.Add("application/form-data");
operation.parameters.Add(new Parameter
{
name = "file",
@in = "formData",
required = true,
type = "file"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<UploadFilter();
API 文档展示效果
接口函数一旦发布就不能改了在线api接口文档系统，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。
著名悲剧在线api接口文档系统：unix 在线api接口文档系统的 creat
2. 不仅是英文单词不要拼错，时态也不要错。
比如在线api接口文档系统：
返回bool在线api接口文档系统的判断函数，单数要用 is 复数要用are，这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。
3. 函数最好是动宾结构
动宾结构就是 doSomething，这样的函数命名含义明确
比如： openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语
4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor
5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音
比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。
Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。
6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。
坏例子: count-cnt, manager-mngr password-pw button-btn
现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。
7. 保持方法的对称性，有些方法一旦出现就应该是成对的，
比如 有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。
如果 open对应clear就有点让人困惑了。
本文目录一览：
- 1、还在发愁写API文档？推荐一款阿里腾讯都在用的API管理神器
- 2、API接口入门（一）：读懂API接口文档
- 3、六大接口管理平台，总有一款适合你的！
- 4、如何使 WebAPI 自动生成漂亮又实用在线API文档
- 5、如何优雅的“编写”api接口文档
- 6、请教在线文档的api
还在发愁写API文档？推荐一款阿里腾讯都在用的API管理神器
作为一个前后端分离模式开发的团队，我们经常会看到这样的场景：前端开发和后端开发在一起热烈的讨论“你这接口参数怎么又变了？”，“接口怎么又不通了？”，“稍等，我调试下”，“你再试试..."。
那能不能写好接口文档，大家都按文档来开发？很难，因为写文档、维护文档比较麻烦，而且费时，还会经常出现 API 更新了，但文档还是旧的，各种同步不一致的情况，从而耽搁彼此的时间。
之前我们团队也遇到了同样的问题，那么作为研发团队的负责人，我是如何带领团队解决这个问题的呢？
方法其实很简单，如果能做到让写文档/维护文档这件事情的短期收益就能远高于付出的成本，那么所有问题都能迎刃而解，开发人员就会非常乐意去写接口文档。
要做到写文档和及时维护文档的短期收益就能远高于付出的成本，无非两个方向：
鉴于此，我们设想如果有一款工具做到以下这些是不是就非常爽了？
总结下来，我们需要的就是这么一款工具：
为此，我们几乎尝遍了市面上所有相关的工具，但是很遗憾，没有找到合适的。
于是，我们自己实现了一个Postman + Swagger + RAP + JMeter
这个工具就是 Apifox，经常很长一段时间不断更新迭代后，我们基本上完全实现了最初的设想，几乎完美解决了最开始遇到的所有问题，在公司内部大受欢迎。并且也形成了我们自己的最佳实践。
没错，现在我们已经将Apifox产品化对外服务了，你们团队也可以直接使用Apifox了。
官网：www.apifox.cn
Apifox = Postman + Swagger + Mock + JMeter
Apifox 是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台。
通过一套系统、一份数据，解决多个系统之间的数据同步问题。只要定义好接口文档，接口调试、数据 Mock、接口测试就可以直接使用，无需再次定义；接口文档和接口开发调试使用同一个工具，接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确！
节省研发团队的每一分钟！
如果你认为 Apifox 只做了数据打通，来提升研发团队的效率，那就错了。Apifox 还做了非常多的创新，来提升开发人员的效率。
通常一个接口会有多种情况用例，比如 正确用例 参数错误用例 数据为空用例 不同数据状态用例。定义接口的时候定义好这些不同状态的用例，接口调试的时候直接运行，非常高效。
可以独立定义数据模型，接口定义时可以直接引用数据模型，数据模型之间也可以相互引用。同样的数据结构，只需要定义一次即可多处使用；修改的时候只需要修改一处，多处实时更新，避免不一致。
使用 Apifox 调试接口的时候，系统会根据接口文档里的定义，自动校验返回的数据结构是否正确，无需通过肉眼识别，也无需手动写断言脚本检测，非常高效！
Apifox 自动校验数据结构
设置断言：
Apifox 设置断言
运行后，查看断言结果：
先放一张图对比下 Apifox 和其他同类工具 零配置 mock 出来的数据效果：
Apifox Mock 数据结果对比同类工具
可以看出 Apifox 零配置 Mock 出来的数据和真实情况是非常接近的，前端开发可以直接使用，而无需再手动写 mock 规则。
「Apifox 如何做到高效率、零配置生成非常人性化的 mock 数据」
Apifox 项目可“在线分享” API 文档，分享出去的 API 文档可设置为公开或需要密码访问，非常方便与外部团队协作。
体验地址：https://www.apipark.cn/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285
根据接口模型定义，自动生成各种语言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等）的业务代码（如 Model、Controller、单元测试代码等）和接口请求代码。目前 Apifox 支持 130 种语言及框架的代码自动生成。
更重要的是：你可以通过自定义代码模板来生成符合自己团队的架构规范的代码，满足各种个性化的需求。
接口调试
Apifox 多种主题色可选
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/
六大接口管理平台，总有一款适合你的！
先聊一聊前端和后端分离的优点。前后端分离优点如下：其中不可避免的就是定制好接口文档，后端工程师要写好单元测试，推荐使用 chrome 的插件 postman 或 soapui或 jmeter，service 层的测试用例拿 junit 写。
但是这种情况对于接口文档管理很不方便，所以下面就罗列一些互联网公司常用的接口文档管理平台。
Swagger是一个大型的API开发者的工具框架，该框架提出了一个编写OpenAPI的规范（命名为OAS），并且Swagger可以跨整个API生命周期进行开发，从设计和文档到测试和部署。
Swagger框架三核心：
YApi部署流程介绍
YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。它可以帮助开发者轻松创建、发布、以及维护API。除此之外，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。特性:
难点：如果需要要执行自动化测试，需要编写脚本。
Eolinker是国内企业级IT研发管理解决方案服务品牌，在线API接口管理服务供应商，致力于满足各行业客户在不同应用环境中对研发管理全生命周期的个性化需求，提供API开发管理（AMS）、开发团队协作、自动化测试、网关（AGW）以及监控（AMT）等服务。
特性：
ShowDoc一个非常适合IT团队的在线API文档、技术文档工具。
随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供API，APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。
项目地址： https://www.showdoc.cc
DOClever是一个可视化接口管理工具 ,可以分析接口结构，校验接口正确性， 围绕接口定义文档，通过一系列自动化工具提升我们的协作效率。
特性：
DOClever官网： http://www.doclever.cn/controller/index/index.html
DOClever GitHub： https://github.com/sx1989827/DOClever
阿里妈妈前端团队出品的开源接口管理工具RAP第二代，RAP通过GUI工具帮助WEB工程师更高效的管理接口文档，同时通过分析接口结构自动生成Mock数据、校验真实接口的正确性，使接口文档成为开发流程中的强依赖。有了结构化的API数据，RAP可以做的更多，而我们可以避免更多重复劳动。基于RAML的接口定义、文档生成、Mock Server完成了定义和使用的分离，通过一套规范完成的接口定义，可以用不同的工具得到适应不同API管理系统的输出，有更多的可能性，同时保持了核心定义不变。RAP较之于RAML，前者更加集中，所有的定义、文档、mock都在同一个服务中完成，并且实时生效，方便快捷，如果只考虑方便易用，RAP是更好的选择，而RAML显得更加繁琐，更适合于公开的接口定义，方便在各个系统之间流转。
github源码地址： https://github.com/thx/rap2-delos
如何使 WebAPI 自动生成漂亮又实用在线API文档
1.1 SwaggerUISwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用（官方demo）。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。
1.2 Swashbuckle
Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。
2.快速开始
创建项目 OnlineAPI来封装百度音乐服务(示例下载) ，通过API可以搜索、获取音乐的信息和播放连接。
我尽量删除一些我们demo中不会用到的一些文件，使其看上去比较简洁。
WebAPI 安装 Swashbuckle
Install-Package Swashbuckle
代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的，生成 SwaggerUI，JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相关展示行为的。如图：
将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));
并在当前类中添加一个方法
/// <summary
/// </summary
/// <param name="name"</param
/// <returns</returns
protected static string GetXmlCommentsPath(string name)
{
return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}
紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”，编译过程中生成类库的注释文件
添加百度音乐 3个API
访问 lt;youhost/swagger/ui/index,最终显示效果
我们通过API 测试API 是否成功运行
3.添加自定义HTTP Header
在开发移动端 API时常常需要验证权限，验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可
首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
public class HttpHeaderFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry
schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null) operation.parameters = new
List<Parameter();
var filterPipeline =
apiDescription.ActionDescriptor.GetFilterPipeline();
//判断是否添加权限过滤器
var isAuthorized = filterPipeline.Select(filterInfo =
filterInfo.Instance).Any(filter = filter is IAuthorizationFilter);
//判断是否允许匿名方法
var allowAnonymous =
apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute().Any();
if (isAuthorized !allowAnonymous)
{
operation.parameters.Add(new Parameter
{
name = "access-key",
@in = "header",
description = "用户访问Key",
required = false,
type = "string"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<HttpHeaderFilter();
添加Web权限过滤器
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class AccessKeyAttribute : AuthorizeAttribute
{
/// <summary
/// 权限验证
/// </summary
/// <param name="actionContext"</param
/// <returns</returns
protected override bool IsAuthorized(HttpActionContext actionContext)
{
var request = actionContext.Request;
if (request.Headers.Contains("access-key"))
{
var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
//TODO 验证Key
return accessKey == "123456789";
}
return false;
}
/// <summary
/// 处理未授权的请求
/// </summary
/// <param name="actionContext"</param
protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)
{
var content = JsonConvert.SerializeObject(new {State = HttpStatusCode.Unauthorized});
actionContext.Response = new HttpResponseMessage
{
Content = new StringContent(content, Encoding.UTF8, "application/json"),
StatusCode = HttpStatusCode.Unauthorized
};
}
}
}
在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]
最终显示效果
4.显示上传文件参数
SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似，只是我们通过特殊的设置来标示API具有上传文件的功能
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;
namespace OnlineAPI.Utility
{
/// <summary
///
/// </summary
public class UploadFilter : IOperationFilter
{
/// <summary
/// 文件上传
/// </summary
/// <param name="operation"</param
/// <param name="schemaRegistry"</param
/// <param name="apiDescription"</param
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (!string.IsNullOrWhiteSpace(operation.summary) operation.summary.Contains("upload"))
{
operation.consumes.Add("application/form-data");
operation.parameters.Add(new Parameter
{
name = "file",
@in = "formData",
required = true,
type = "file"
});
}
}
}
}
在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<UploadFilter();
API 文档展示效果
如何优雅的“编写”api接口文档
1. 拼写要准确接口函数一旦发布就不能改了在线api接口文档系统，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。
著名悲剧在线api接口文档系统：unix 在线api接口文档系统的 creat
2. 不仅是英文单词不要拼错，时态也不要错。
比如在线api接口文档系统：
返回bool在线api接口文档系统的判断函数，单数要用 is 复数要用are，这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。
3. 函数最好是动宾结构
动宾结构就是 doSomething，这样的函数命名含义明确
比如： openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语
4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor
5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音
比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。
Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。
6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。
坏例子: count-cnt, manager-mngr password-pw button-btn
现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。
7. 保持方法的对称性，有些方法一旦出现就应该是成对的，
比如 有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。
如果 open对应clear就有点让人困惑了。
请教在线文档的api
Android中文版
api手册地址：http://www.matools.com/api/android
Ant最新版
api手册地址：http://www.matools.com/api/ant
ASM字节码操作
api手册地址：http://www.matools.com/api/asm
Axis2最新版
api手册地址：http://www.matools.com/api/axis2
Bash脚本
api手册地址：http://www.matools.com/api/bash
Bootstrap 3
api手册地址：http://www.matools.com/api/bootstrap3
Bootstrap 4
api手册地址：http://www.matools.com/api/bootstrap4
C/C++
api手册地址：http://www.matools.com/api/c
C3P0连接池
api手册地址：http://www.matools.com/api/c3p0
CentOS使用文档
api手册地址：http://www.matools.com/api/centos
Commons-Beanutils
api手册地址：http://www.matools.com/api/commons-beanutils
Commons-Fileupload
api手册地址：http://www.matools.com/api/commons-fileupload
Commons-IO最新版
api手册地址：http://www.matools.com/api/commons-io
Commons-Lang最新版
api手册地址：http://www.matools.com/api/commons-long
Commons-Net最新版
api手册地址：http://www.matools.com/api/commons-net
CSS 3
api手册地址：http://www.matools.com/api/css
DBCP连接池
api手册地址：http://www.matools.com/api/dbcp
Dom4j
api手册地址：http://www.matools.com/api/dom4j
dubbo中文文档
api手册地址：http://www.matools.com/api/dubbo
EhCache
api手册地址：http://www.matools.com/api/ehcache
Freemarker
api手册地址：http://www.matools.com/api/freemarker
Go语言
api手册地址：http://www.matools.com/api/go
Hadoop
api手册地址：http://www.matools.com/api/hadoop
Hibernate中文版
api手册地址：http://www.matools.com/api/hibernate
IKAnalyzer中文版
api手册地址：http://www.matools.com/api/ikanalyzer
Java 10
api手册地址：http://www.matools.com/api/java10
Java 6
api手册地址：http://www.matools.com/api/java6
Java 7
api手册地址：http://www.matools.com/api/java7
Java 8中文版
api手册地址：http://www.matools.com/api/java8
jqGrid中文版
api手册地址：http://www.matools.com/api/jqgrid
Jquery中文版
api手册地址：http://www.matools.com/api/jquery
Json-lib
api手册地址：http://www.matools.com/api/json-lib
Junit4最新版
api手册地址：http://www.matools.com/api/junit
Kryo
api手册地址：http://www.matools.com/api/kryo
Log4j最新版
api手册地址：http://www.matools.com/api/log4j
Lucene
api手册地址：http://www.matools.com/api/lucene
Maven
api手册地址：http://www.matools.com/api/maven
Windows MFC中文版
api手册地址：http://www.matools.com/api/msdn
Mybatis
api手册地址：http://www.matools.com/api/mybatis
MySql中文版
api手册地址：http://www.matools.com/api/mysql
Netty 3.6
api手册地址：http://www.matools.com/api/netty
Nginx中文版
api手册地址：http://www.matools.com/api/nginx
OpenJPA最新版
api手册地址：http://www.matools.com/api/openjpa
PHP中文版
api手册地址：http://www.matools.com/api/php
POI-apache
api手册地址：http://www.matools.com/api/poi
QuickServer
api手册地址：http://www.matools.com/api/quickserver
redis中文参考文档
api手册地址：http://www.matools.com/api/redis
Ruby
api手册地址：http://www.matools.com/api/ruby
Ruby-library
api手册地址：http://www.matools.com/api/ruby-library
Ruby on Rails
api手册地址：http://www.matools.com/api/rubyonrails
Shiro
api手册地址：http://www.matools.com/api/shiro
Spring最新版
api手册地址：http://www.matools.com/api/spring
Spring for Android
api手册地址：http://www.matools.com/api/spring-android
Spring Boot
api手册地址：http://www.matools.com/api/spring-boot
Spring Cloud中文文档
api手册地址：http://www.matools.com/api/spring-cloud
Spring Security
api手册地址：http://www.matools.com/api/spring-security
Spring中文版
api手册地址：http://www.matools.com/api/spring-zh
Struts 2最新版
api手册地址：http://www.matools.com/api/struts2
Taperstry
api手册地址：http://www.matools.com/api/taperstry
TensorFlow中文
api手册地址：http://www.matools.com/api/tensorflow
Tomcat
api手册地址：http://www.matools.com/api/tomcat
Ubuntu
api手册地址：http://www.matools.com/api/ubuntu
Velocity 1.7
api手册地址：http://www.matools.com/api/velocity
VelocityTools2.0
api手册地址：http://www.matools.com/api/velocity-tools
Vue Router中文参考
api手册地址：http://www.matools.com/api/vue-router
vue.js中文文档
api手册地址：http://www.matools.com/api/vuejs
XMLBeans
api手册地址：http://www.matools.com/api/xmlbeans
Yahoo UI中文版
api手册地址：http://www.matools.com/api/yui
Zend Framework中文版
api手册地址：http://www.matools.com/api/zend-framework
Zookeeper
api手册地址：http://www.matools.com/api/zookeeper
版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。
相关文章
推荐文章
最近发表
