如何做到 API 文档规范化？

定义一个好的 API 文档是优秀研发人员的标准配置，在执行接口测试之前，测试人员一定会先拿到开发给予的接口文档。

测试人员可以根据这个文档编写接口测试用例，优秀的文档可以区分好的用户体验和坏的用户体验。它不仅可以帮助优化工作流程，还可以帮助前端工程师和测试工程师更好的规划自己的任务。作为一名互联网程序员，我们应该学习如何高效的输出一份优秀的 API 技术文档。

首先我们需要了解接口文档的主要构成及含义，完整的接口文档有公共信息说明、请求响应、接口签名 DEMO、加签代码示例、接口功能说明、接口参数详细说明 5个部分组成。

1、公共信息说明：

公共信息说明页为公共参数说明及请求受理结果代码两部分：公共参数说明填写多个接口提取的通用参数，这里可以分为请求参数及影响参数。需要填写参数名称，类型，最大长度，描述和用法。请求受理结果代码就是影响码的说明。

2、请求，相应及加签 DEMO

请求，响应及加签 DEMO 页，一般这个页面会描述加签的过程，例如分为 rsa 加签私钥和服务参数说明。服务参数需要进行以下说明；

1. 对参数名进行从小到大的排序

2. 对参数及参数值拼接成字符串

3. 用 RSA 对参数串进行加签后用 base64 编码，获得签名串

4. 对各个参数值进行参数值特殊字符的转义

5. 请求体说明

3、加签代码示例

加签代码示例部分会填写加签的代码实例，测试人员可以根据加签代码编写测试代码。

4、接口功能说明

接口功能说明填写各接口的重要信息，包含借口名称，接口类型，接口服务代码，接口版本号，备注。

5、接口参数详细说明

接口参数详细说明填写接口的主要信息及参数信息。主要信息有服务名称，服务代码，服务版本号，服务功能描述，服务提供方系统，服务消费方系统。参数说明可分为描述，类型，子段长度，是否必填，说明。

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

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 Apikit 以服务形式存在的接口文档，它可以伴随代码的变更同步变化，这就减少了很多开发工程师和测试工程师之间的沟通成本。

这些编写方式都可以应用于目前的工作，简单、有⽤、可发现、⼀致、可预测，所有这些不仅描述了良好的 API，还描述了良好的产品。这不是偶然的，当你编写 API 时，你将创建⼀个产品。

API 文档的可维护性

对于 API 文档的可维护性应该保持像维护一个单独项目一样，每次通过分支的形式进行更新，编辑人员在检查文档内容的正确性和简介性之后，并由项目组成员进行 review。当 API 文档发布后，后期维护也是同等的重要，主要体现在两个方面：

1. New feature 和废弃功能；当发布新功能之前应该先发布文档，并保证文档通过了标准的review 流程。然而废弃掉的旧功能从文档中移除，并建议在对应的位置给出废弃功能提示和升级指南，确保使用旧功能的开发者进行升级工作

2. 在文档页面上应该预留文档的 contribute 入口，如果文档托管在 GitHub 这样的平台上就提供指向仓库的链接，方便每个阅读文档的用户给文档提 Issue 或者 PR。如果文档是闭源的，也应该至少留有提供反馈信息的位置

关于一些可用性建议

作为开发⼈员，我们很容易忽视这⼀点。根据知识的偏差，假设我们的 API ⽤户是程序员，他们知道我们所知道的，理解我们所理解的，但我们并不认为他们是最终⽤户或客户。要克服这种偏差，换位思考是设计好的 API 的关键思想。所以当你编写下⼀个 API 时，把⾃⼰放在客户的⾓度，想象你想要的是什么。

以上是对项目开发合作中写出友好的 API 文档的一些想法和建议，欢迎讨论。