有效浏览 API 文档的 7 个技巧

API 文档对于开发人员和用户至关重要。通过这 7 个实用技巧和示例，了解如何浏览 API 文档。

什么是 API 文档？

API文档是一组解释如何使用API函数的书面说明。它提供了有关函数、类和返回类型的详细信息，为开发人员和消费者提供构建集成和进行 API 调用所需的信息。

阅读文档将帮助您了解 API 的工作原理，尤其是在文档编写良好的情况下。为了有效地做到这一点，我特别尝试了解以下内容：

身份验证：身份验证和授权是 API 正常工作的基本功能，有助于首先了解哪些身份验证方法可用。您需要了解如何对请求进行身份验证，了解与无效身份验证相关的错误消息，并了解如何以及在哪里获取所选身份验证方法的 API 密钥或流程。
错误：问题肯定会发生，并且对于初学者来说可能会令人生畏。一个好技巧是浏览文档以了解潜在的错误消息、原因和潜在的解决方案。
方法：如果您已经知道要实现的目标，则可以直接查找特定方法和端点。只需确保它们的定义符合您的预期即可。

当我刚开始担任开发人员倡导者时，我很难围绕 API 创建内容，因为我不熟悉用例。所以，这个技巧更适合 API 创建者。尽可能详细说明谁应该使用您的 API 以及如何使用。

它还有助于按顺序显示端点的多种用途以实现目标，例如，提交与支付相关的 API 的订单或创建由不同事件触发的自动电子邮件工作流程以进行报告或警报。

示例是展示 API 全部潜力的好方法。因此，通过良好的代码示例，让开发者消费者能够轻松使用和理解您的 API。如果您能为每个端点提供示例，那就更好了。对于消费者来说，请确保尽可能多地使用所提供的示例。

这个技巧是前一个技巧的延伸。有例子很棒。此外，最好与 API 文档保持一致。例如，如果“创建帐户”操作的输入中有，请避免在响应中将其重命名为。一致性还应该反映在组织的开发者门户或平台中。accountNumberaccountId

假设您的示例提供不同的编程语言，请确保这些语言在功能程度上具有尽可能的一致性。例如，您不希望您的 Python 示例如此复杂且易于理解，而您的 PHP 示例却滞后。最后，坚持领域实践并使用惯用的代码。

一致性增强了用户的开发者体验并提高了创作者的可信度。

这是我最喜欢的技巧之一。在深入研究文档或使用新 API 之前，我会快速检查更改日志，看看我想要使用的 API 是否有任何更改。

在此过程中，我在处理变更日志时牢记以下问题：是否有任何已弃用的端点？还是重大改变？反应身体模型是如何呈现的？有新的必需参数吗？版本号？有什么我应该注意的新端点吗？

通过提出这些问题，我减少了使用上述 API 时的意外因素。如果可能的话，订阅变更日志以随时了解变更也是一个好主意。

维护文档的价值怎么强调都不为过。作为创建者，请确保您有一个根据更新处理文档的策略 - 这可以轻松实现自动化。实用的维护解决方案是采用当今可用工具的标准化流程，例如OpenAPI 规范或 Postman。

在我的成长过程中，我总是被鼓励让空间、地方和家庭比我发现时更好。所以，我挑战你也这样做。文档永远不可能是完美的，但它总是可以变得更好，因此请通过创建包含改进建议的 PR、在发现错误时提出问题或提供反馈（无论好坏）来发挥自己的作用。它不仅可以帮助创作者，还可以为下一个用户提供更好的体验。