乐趣区

关于api文档:如何做到-API-文档规范化

jiezi

定义一个好的 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 文档的一些想法和倡议，欢送探讨。

退出移动版