如何做到API文档规范化
定义一个好的 API 文档是优秀研发人员的标准配置,在执行接口测试之前,测试人员一定会先拿到开发给予的接口文档。
测试人员可以根据这个文档编写接口测试用例,优秀的文档可以区分好的用户体验和坏的用户体验。它不仅可以帮助优化工作流程,还可以帮助前端工程师和测试工程师更好的规划自己的任务。作为一名互联网程序员,我们应该学习如何高效的输出一份优秀的 API 技术文档。
首先我们需要了解接口文档的主要构成及含义,完整的接口文档有公共信息说明、请求响应、接口签名 DEMO、加签代码示例、接口功能说明、接口参数详细说明 5个部分组成。
1、公共信息说明:
公共信息说明页为公共参数说明及请求受理结果代码两部分:公共参数说明填写多个接口提取的通用参数,这里可以分为请求参数及影响参数。需要填写参数名称,类型,最大长度,描述和用法。请求受理结果代码就是影响码的说明。
2、请求,相应及加签 DEMO
请求,响应及加签 DEMO 页,一般这个页面会描述加签的过程,例如分为 rsa 加签私钥和服务参数说明。服务参数需要进行以下说明:
对参数名进行从小到大的排序
对参数及参数值拼接成字符串
用 RSA 对参数串进行加签后用 base64 编码,获得签名串
对各个参数值进行参数值特殊字符的转义
请求体说明
3、加签代码示例
加签代码示例部分会填写加签的代码实例,测试人员可以根据加签代码编写测试代码。
4、接口功能说明
接口功能说明填写各接口的重要信息,包含借口名称,接口类型,接口服务代码,接口版本号,备注。
5、接口参数详细说明
接口参数详细说明填写接口的主要信息及参数信息。主要信息有服务名称,服务代码,服务版本号,服务功能描述,服务提供方系统,服务消费方系统。参数说明可分为描述,类型,子段长度,是否必填,说明。
通过以上我们可以读懂接口文档也是接口测试的重要环节。通过对工作中接口文档的详解,指导测试人员如何理解接口文档,进而通过接口文档编写接口测试用例。
API 文档的重要性
API 文档是人类和机器可读的技术内容,用于解释特定 API 的工作原理及其功能。它的目的是双重的。如果做得正确的话,API 文档将成为 API 工作方式的一个真正信息来源。它应该以结构化格式包含函数、参数、类等的详细信息,便于开发人员和非技术用户理解。通常,它包括教程和示例,帮助用户更好地理解不同部分如何协同工作。
由于有许多不同类型的文档,很难使事情井然有序。API 需要参考、指南和其他内容来帮助开发人员。另外 API 支持的产品可能需要自己的参考资料,包括屏幕截图和视频。
什么是好的 API 文档?
一个好的 API 文档,除了内容合理详细之外,它的样式和交互方式也要简单易用。现在的 API 文档基本基于网页来展现,利用网页的显示特性,有一些比较常见的设计方式。在这里推荐一些适合作为 API 文档展现要素的一些最佳实践。
许多流行的工具在线发布他们的 API 文档,以便第三方开发人员可以轻松访问它们。以下是这些文档如此有效的一些原因:
在文档中提供了示例代码,以便用户可以看到API在实践中是如何工作的
轻松找到常见问题的解决方案,以便忙碌的开发人员可以快速获得所需的内容
不提供理解 API 及其工作方式之外的不必要信息。当用户忙于工作并遇到问题时,他们需要可用的文档,而不是无关的信息
不需要设限知识水平;最简单的概念和最困难的概念一样得到充分解释
格式良好。内容有条理且一致且易于阅读。这减少了希望学习或解决问题的用户的摩擦。
文档的工具要求
想要一个工具来处理所有类型的文档是很自然的。考虑 API 文档,通常需要与工程团队协作。将API文档硬塞进帮助文档平台可能行不通。工程团队处于版本控制中,例如 Git,因此即使是复制粘贴到 CMS 的手动过程也无法完成。随着工程对 API 进行更改,文档需要随之更改,生成 API 参考将确保避免许多潜在的麻烦。
最佳的编写方式
编写 API 文档的方式不仅一种,不同的软件有不同的使用规范,这些规范都各自提供了描述 API 的不同标准和风格,以下三四种仅为参考:
OpenAPI(以前称为 Swagger)–最受欢迎的规范。开源,并得到 Microsoft 和 Google 等公司的支持。使用具有特定架构的 JSON/YAML 对象来描述 API 元素。
API Blueprint 另一个开放源代码规范,API 蓝图旨在提供高度可访问性。它使用类似于 Markdown 的描述语言,并且在 API 创建过程中遵循设计优先原则的情况下表现出色。
RAML–基于 YAML 的 RAML(或 RESTful API 建模语言)采用自上而下的方法来创建清晰,一致和精确的文档。
Eolink Apikit 以服务形式存在的接口文档,它可以伴随代码的变更同步变化,这就减少了很多开发工程师和测试工程师之间的沟通成本。
这些编写方式都可以应用于目前的工作,简单、有⽤、可发现、⼀致、可预测,所有这些不仅描述了良好的 API,还描述了良好的产品。这不是偶然的,当你编写 API 时,你将创建⼀个产品。
API 文档的可维护性
对于 API 文档的可维护性应该保持像维护一个单独项目一样,每次通过分支的形式进行更新,编辑人员在检查文档内容的正确性和简介性之后,并由项目组成员进行 review。当 API 文档发布后,后期维护也是同等的重要,主要体现在两个方面:
New feature 和废弃功能;当发布新功能之前应该先发布文档,并保证文档通过了标准的review 流程。然而废弃掉的旧功能从文档中移除,并建议在对应的位置给出废弃功能提示和升级指南,确保使用旧功能的开发者进行升级工作
在文档页面上应该预留文档的 contribute 入口,如果文档托管在 GitHub 这样的平台上就提供指向仓库的链接,方便每个阅读文档的用户给文档提 Issue 或者 PR。如果文档是闭源的,也应该至少留有提供反馈信息的位置
关于一些可用性建议
作为开发⼈员,我们很容易忽视这⼀点。根据知识的偏差,假设我们的 API ⽤户是程序员,他们知道我们所知道的,理解我们所理解的,但我们并不认为他们是最终⽤户或客户。要克服这种偏差,换位思考是设计好的 API 的关键思想。所以当你编写下⼀个 API 时,把⾃⼰放在客户的⾓度,想象你想要的是什么。
以上是对项目开发合作中写出友好的 API 文档的一些想法和建议,欢迎讨论。
如何做到API文档规范化的更多相关文章
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- Core Web API上使用Swagger提供API文档
在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...
- Day01:API文档 / 字符串基本操作
JDK API 什么是JDK API? JDK中包含大量的API类库,所谓AP就是一些写好的,可提供直接调用的功能(在Java语言中,这些功能以类的形式封装). JDK API包含的类库功能强大,经常 ...
- 微服务系列之Api文档 swagger整合
1.前言 微服务架构随之而来的前后端彻底分离,且服务众多,无论是前后端对接亦或是产品.运营翻看,一个现代化.规范化.可视化.可尝试的文档是多么重要,所以我们这节就说说swagger. Swagger是 ...
- Java在DOS命令下的运行及其API文档制作过程
该文档主要描述java程序在DOS命令下的运行,以及一些常用的命令 常用DOS命令: d: 回车 盘符切换 dir(directory):列出当前目录下的文件以及文件夹 md (make direct ...
- 利用sphinx为python项目生成API文档
sphinx可以根据python的注释生成可以查找的api文档,简单记录了下步骤 1:安装 pip install -U Sphinx 2:在需要生成文档的.py文件目录下执行sphinx-apido ...
- 如何使 WebAPI 自动生成漂亮又实用在线API文档
1.前言 1.1 SwaggerUI SwaggerUI 是一个简单的Restful API 测试和文档工具.简单.漂亮.易用(官方demo).通过读取JSON 配置显示API. 项目本身仅仅也只依赖 ...
- Android多媒体--MediaCodec 中文API文档
*由于工作需要,需要利用MediaCodec实现Playback及Transcode等功能,故在学习过程中翻译了Google官方的MediaCodec API文档,由于作者水平限制,文中难免有错误和不 ...
- 新手如何查看API文档?
Java API文档为例: 1:知道包名,可以在Overview里直接找到这个包,然后去查这个包下面的类和方法.2:知道类名和方法名,可以在Index.html里直接去找这个类或方法,然后查看.3:如 ...
- Bullet的学习资源(用Doxygen生成API文档)
Bullet 全称 Bullet Physics Library,是著名的开源物理引擎(可用于碰撞检测.刚体模拟.可变形体模拟),这里将bullet的学习资源整理一下,希望能帮助入门者少走弯路. 看下 ...
随机推荐
- Erlang Mnesia数据库迁移方法
本文参考https://blog.csdn.net/yangzm/article/details/51686249 需求 因为一些原因,需要把一个Mnesia节点的数据库搬迁到另一个节点,然后弃用原来 ...
- 【Leetcode第286场周赛】——周赛总结
1.5268. 找出两数组的不同 - 力扣(LeetCode) (leetcode-cn.com) 给你两个下标从 0 开始的整数数组 nums1 和 nums2 ,请你返回一个长度为 2 的列表 a ...
- c++ dll 传递string参数
用c++编写了一个dll,需要传递一个路径的变量参数,刚开始想着使用string变量,但是在实践过程中string变量会成为乱码,尽量避免使用string变量传递参数,可以使用const char* ...
- 源代码管理工具:Github
GitHub是一个基于Git的进行版本控制的代码托管网站. Git指的是是一个开放源代码版本控制系统,由Linus Torvalds启动.在时间的累积下,现在的Github是一个最大的开源软件社区.在 ...
- Filbeat采集nginx-ingress日志
一.创建configmap配置文件 注:filebeat6以上版本需要将prospectors改为inputs,paths下指定的nginx-ingress日志路径匹配模式以及hosts指定的kafk ...
- vue-固定头部-内容可滚动
<div class="show-box"> <div class="show-top"> ...
- ssm框架基本原理
一.前言 SM框架是标准的MVC模式,将整个系统划分为四层:View层,Controller层,Service层,Dao层 SSM(Spring+SpringMVC+MyBatis)框架集由Sprin ...
- openstack安装部署私有云详细图文
本文主要分享的是云计算.openstack的使用.私有云平台建设.云服务器云硬盘的构建和使用.从基本概念入手到私有云建设,信息量非常大.对于openstack的安装部署都是从官方文档中一步步的介绍,内 ...
- (三).JavaScript的分支结构和循环结构
1. 分支结构 1.1 分支语句之单分支 ①.语法: if(值,如果不是布尔值会强制转换成布尔值) { 代码块; } ②.案例: // 案例:如果a变量的值加键盘上输入的数大于100,就打印我爱你二狗 ...
- MYSQL DUAL(伪表)
#DUAL是一个伪表,不存在的表. SELECT 8*9 FROM DUAL #输出72