如何做到API文档规范化

2022-09-15  微不足道 

定义一个好的API文档是优秀研发人员的标准配置,在执行接口测试之前,测试人员一定会先拿到开发给予的接口文档。
测试人员可以根据这个文档编写接口测试用例,优秀的文档可以区分好的用户体验和坏的用户体验。它不仅可以帮助优化工作流程,还可以帮助前端工程师和测试工程师更好的规划自己的任务。作为一名互联网程序员,我们应该学习如何高效的输出一份优秀的API技术文档。
首先我们需要了解接口文档的主要构成及含义,完整的接口文档有公共信息说明,请求响应及接口签名DEMO,加签代码示例,接口功能说明,接口参数详细说明5个部分组成。
a,公共信息说明:
公共信息说明页为公共参数说明及请求受理结果代码两部分:公共参数说明填写多个接口提取的通用参数,这里可以分为请求参数及影响参数。需要填写参数名称,类型,最大长度,描述和用法。请求受理结果代码就是影响码的说明。
b,请求,相应及加签DEMO
请求,响应及加签DEMO页,一般这个页面会描述加签的过程,例如分为rsa加签私钥和服务参数说明。服务参数需要进行以下说明;

  1. 对参数名进行从小到大的排序
  2. 对参数及参数值拼接成字符串
  3. 用RSA对参数串进行加签后用base64编码,获得签名串
  4. 对各个参数值进行参数值特殊字符的转义
  5. 请求体说明

c,加签代码示例
加签代码示例部分会填写加签的代码实例,测试人员可以根据加签代码编写测试代码。
d,接口功能说明
接口功能说明填写各接口的重要信息,包含借口名称,接口类型,接口服务代码,接口版本号,备注。
e,接口参数详细说明
接口参数详细说明填写接口的主要信息及参数信息。主要信息有服务名称,服务代码,服务版本号,服务功能描述,服务提供方系统,服务消费方系统。参数说明可分为描述,类型,子段长度,是否必填,说明。

通过以上我们可以读懂接口文档也是接口测试的重要环节。通过对工作中接口文档的详解,指导测试人员如何理解接口文档,进而通过接口文档编写接口测试用例。

API 文档的重要性
API 文档是人类和机器可读的技术内容,用于解释特定 API 的工作原理及其功能。它的目的是双重的。如果做得正确的话,API 文档将成为 API 工作方式的一个真正信息来源。它应该以结构化格式包含函数、参数、类等的详细信息,便于开发人员和非技术用户理解。通常,它包括教程和示例,帮助用户更好地理解不同部分如何协同工作。
由于有许多不同类型的文档,很难使事情井然有序。API 需要参考、指南和其他内容来帮助开发人员。另外 API 支持的产品可能需要自己的参考资料,包括屏幕截图和视频。

什么是好的 API 文档?
一个好的 API 文档,除了内容合理详细之外,它的样式和交互方式也要简单易用。现在的 API 文档基本基于网页来展现,利用网页的显示特性,有一些比较常见的设计方式。在这里推荐一些适合作为 API 文档展现要素的一些最佳实践。
许多流行的工具在线发布他们的 API 文档,以便第三方开发人员可以轻松访问它们。以下是这些文档如此有效的一些原因:

  1. 在文档中提供了示例代码,以便用户可以看到API在实践中是如何工作的
  2. 轻松找到常见问题的解决方案,以便忙碌的开发人员可以快速获得所需的内容
  3. 不提供理解 API 及其工作方式之外的不必要信息。当用户忙于工作并遇到问题时,他们需要可用的文档,而不是无关的信息
  4. 不需要设限知识水平;最简单的概念和最困难的概念一样得到充分解释
    格式良好。内容有条理且一致且易于阅读。这减少了希望学习或解决问题的用户的摩擦。

文档的工具要求
想要一个工具来处理所有类型的文档是很自然的。考虑 API 文档,通常需要与工程团队协作。将API文档硬塞进帮助文档平台可能行不通。工程团队处于版本控制中,例如 Git,因此即使是复制粘贴到 CMS 的手动过程也无法完成。随着工程对 API 进行更改,文档需要随之更改,生成 API 参考将确保避免许多潜在的麻烦。

最佳的编写方式
编写API文档的方式不仅一种,不同的软件有不同的使用规范,这些规范都各自提供了描述API的不同标准和风格,以下三四种仅为参考:

  1. OpenAPI(以前称为Swagger)–最受欢迎的规范。开源,并得到Microsoft和Google等公司的支持。使用具有特定架构的JSON/YAML对象来描述API元素
  2. API Blueprint 另一个开放源代码规范,API蓝图旨在提供高度可访问性。它使用类似于Markdown的描述语言,并且在API创建过程中遵循设计优先原则的情况下表现出色
  3. RAML–基于YAML的RAML(或RESTful API建模语言)采用自上而下的方法来创建清晰,一致和精确的文档
  4. Eolink以服务形式存在的接口文档,它可以伴随代码的变更同步变化,这就减少了很多开发工程师和测试工程师之间的沟通成本。

这些编写方式都可以应用于目前的工作,简单、有⽤、可发现、⼀致、可预测,所有这些不仅描述了良好的API,还描述了良好的产品。这不是偶然的,当你编写API时,你将创建⼀个产品。
API 文档的可维护性
对于API文档的可维护性应该保持像维护一个单独项目一样,每次通过分支的形式进行更新,编辑人员在检查文档内容的正确性和简介性之后,并由项目组成员进行review。当API文档发布后,后期维护也是同等的重要,主要体现在两个方面:

  1. New feature 和废弃功能;当发布新功能之前应该先发布文档,并保证文档通过了标准的review 流程。然而废弃掉的旧功能从文档中移除,并建议在对应的位置给出废弃功能提示和升级指南,确保使用旧功能的开发者进行升级工作
  2. 在文档页面上应该预留文档的 contribute 入口,如果文档托管在 GitHub 这样的平台上就提供指向仓库的链接,方便每个阅读文档的用户给文档提 Issue 或者 PR。如果文档是闭源的,也应该至少留有提供反馈信息的位置
    关于一些可用性建议
    作为开发⼈员,我们很容易忽视这⼀点。根据知识的偏差,假设我们的API⽤户是程序员,他们知道我们所知道的,理解我们所理解的,但我们并不认为他们是最终⽤户或客户。要克服这种偏差,换位思考是设计好的API的关键思想。所以当你编写下⼀个API时,把⾃⼰放在客户的⾓度,想象你想要的是什么。
    以上是对项目开发合作中写出友好的 API 文档的一些想法和建议,欢迎讨论。
140°/1408 人阅读/0 条评论 发表评论

登录 后发表评论