自动化接口api文档（接口自动化平台开发）

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

本文目录一览：

• 1、如何优雅的“编写”api接口文档
• 2、如何使 WebAPI 自动生成漂亮又实用在线API文档
• 3、还在发愁写API文档？推荐一款阿里腾讯都在用的API管理神器
• 4、Restful接口文档规范
• 5、适用于Mac系统的API接口调试应用
• 6、apifox是什么软件

如何优雅的“编写”api接口文档

1. 拼写要准确
接口函数一旦发布就不能改了，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。
著名悲剧：unix 的 creat
2. 不仅是英文单词不要拼错，时态也不要错。
比如：
返回bool的判断函数，单数要用 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就有点让人困惑了。

如何使 WebAPI 自动生成漂亮又实用在线API文档

1.1 SwaggerUI
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管理神器

作为一个前后端分离模式开发自动化接口api文档的团队，自动化接口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 和其自动化接口api文档他同类工具 零配置 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 多种主题色可选

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】、数据类型、是否必填、中文描述。

相应参数：类型、中文描述。

适用于Mac系统的API接口调试应用

Apifox 中文版是一款适用于 Mac 的API接口调试应用。官方介绍 Apifox = Postman + Swagger + Mock。Apifox 可以用于接口文档、接口调试、Mock、自动化测试，可以帮助大大提升开发效率！

软件开发过程中，接口管理、调试、自动化测试是必不可少的，我们经常使用 Postman 等工具来进行接口调试，在接口调试方面 Postman 做的非常出色。但是在整个软件开发过程中，接口调试只是其中的一部分，还有很多事情 Postman 无法完成，或者无法高效完成，比如：接口文档定义、Mock 数据、接口自动化测试等等。而 Apifox 就是为此而生的。

可视化接口管理

支持数据结构（JSON Schema）管理，多接口可复用相同数据结构。

接口调试

Postman 有的功能，比如环境变量、预执行脚本、后执行脚本、Cookie/Session 全局共享 等功能，Apifox 都有，并且和 Postman 一样高效好用。

自动校验数据结构

接口调试时，自动校验返回的数据结构是否符合接口文档定义，一键发现接口数据异常。

接口数据 Mock

内置 Mock.js 规则引擎，非常方便 mock 出各种数据，并且可以在定义数据结构的同时写好 mock 规则。 支持自定义期望，灵活配置根据参数值返回不同数据内容。 零配置即可 Mock 出非常人性化的数据。
自动化测试

完善的接口自动化测试功能，保证接口数据的正确性。 支持自定义脚本，自动化检查数据正确性。自定义脚本语法 100% 兼容 Postman，降低学习成本。

数据导入/导出

支持导出 OpenApi (原Swagger)、Markdown、Html 等数据格式。 支持导入 OpenApi格式（原Swagger）、Postman、HAR、RAP2、yapi、Eolinker、DOClever、ApiPost、Apizza 等数据格式。

apifox是什么软件

apifox是自动化测试为一体协作平台。

Apifox是集API文档、API调试、APIMock、API自动化测试为一体的协作平台自动化接口api文档，它将自动化接口api文档我们日常使用的Postman+Swagger+Mock+JMeter进行集成、解决了这些软件之间数据同步的问题。

并且为了最大程度上提高开发人员的便捷性自动化接口api文档，Apifox支持只要定义好API文档，那么API调试、API数据Mock、API自动化测试就可以直接使用，无需再次定义，有效提高软件开发效率，是一个名副其实的高效综合型接口协作工具。

Apifox功能点

API文档，在API文档部分，不在是往日冷冰冰的文档，而是完全可视化、这无疑降低了我们的学习成本、并且文档是遵循OpenAPI规范的，也能提高我们文档的规范性。

API调试，在接口调试部分，我们一个接口可以创建多个用力并且自动跟随接口进行变更，并且Postman用的功能，Apifox都拥有，可以进行环境变量、全局变量、前后置脚本、全局共享等等功能，可谓是全面。并且支持运行任何语言代码：js、java、py、php等。

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

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