2022年与你的团队分享的三个文档趋势

API 曾经主要服务基于文本的数据&＃xff0c;现在它们几乎是每个行业和技术层面的各种SaaS产品背后的引擎。

现在生产和使用 API 的方式甚至比五年前还要复杂。但是 API 文档呢&＃xff1f;

过去&＃xff0c;提供端点列表和一些关于授权令牌的指导足以让开发人员开始使用 API。但随着 API 产品和用例变得越来越复杂&＃xff0c;基本的描述性文档是不够的。更新文档听起来像是一个重大项目&＃xff0c;但现在投资一种可持续的方法可以让团队花在手动更改上的时间以及为用户提供良好体验上获得巨大的回报。

现代化 API 文档意味着结合三个要素&＃xff1a;自动化、可重用性和交互性。让我们深入研究下面的每一个&＃xff0c;以便你可以了解API文档的发展趋势。

自动化文档以跟上开发团队

设计优先的 API 方法非常适合想要频繁且高效地迭代的 API 团队。缩短 API 更新的发布时间表可为用户创造价值&＃xff0c;并使你能够快速适应新的需求。快速迭代的缺点是&＃xff0c;没有人希望放慢发布速度来记录每一个更改。

API维护人员需要时刻记住他们的用户&＃xff0c;但快速迭代有点像一把双刃剑。一方面&＃xff0c;你希望让开发团队腾出时间去做他们最擅长的事情&＃xff0c;而不是陷入文档程序中。同时&＃xff0c;如果 API 消费者没有一种简单的方法来了解并亲自尝试API&＃xff0c;那么所有这些了不起的创新都将毫无用处。

自动化文档是一个很好的一线解决方案&＃xff0c;它可以以一种精确映射到API端点的格式进行文档记录。最基本的自动化文档可以围绕OpenAPI规范构建的开源工具生成。这些工具通过读取你的 OpenAPI 规范文件并将该数据直接输入交互式网络工具来工作。它们启动速度很快&＃xff0c;并且会在你的 OpenAPI 规范文件更改时自动更新。

为一致、灵活的文档创建可重用模块

最好的文档不仅仅是提供信息&＃xff0c;它还具有教育意义和启发意义。我们上面讨论的参考文档是必要的&＃xff0c;但它们不太可能激发你的 API 消费者的创造力或鼓励他们深入挖掘。

为了使你的文档能够实现这些崇高目标&＃xff0c;它需要嵌入到你的开发人员体验中。使用你的产品的开发人员应该经常遇到示例、指南和代码示例&＃xff0c;而不仅仅是在他们寻找它们时。查看更多关于你的 API 的实际使用文档有助于开发人员设想新的集成并加深他们与你的产品的互动。

再一次&＃xff0c;你可能会认为这意味着你的团队需要做更多的工作。优秀文档的另一个关键特征是一致性&＃xff0c;其提供了一些护栏来帮助保持工作的可管理性。开发人员使用模块化代码来确保应用程序按预期运行。模块化、可重用的文档有助于实现相同的目标。

实现相同目标的另一种方法是使用内容标记和过滤。重复的文档让用户和维护者头疼&＃xff0c;但随着文档范围的扩大&＃xff0c;避免重复文档可能具有挑战性。最终目标与可重用模块相同&＃xff0c;一次创建高质量的文档&＃xff0c;并使它们易于查找和重用。

使用交互式文档引导和吸引你的 API 使用者

在某些时候&＃xff0c;决定开始使用你的 API 构建的开发人员将需要一个地方来测试和获取结果。 一些测试类的工具很受欢迎&＃xff0c;它们帮助开发人员使用你的 API &＃xff0c;但仍然需要他们在你的文档和第三方工具之间来回切换&＃xff0c;并且不会为你提供深入了解他们最初的开发人员经验。

作为文档的一部分提供交互式功能是满足开发人员需求并加强他们与你的产品的联系的一种方式。第三方工具需要开发者通过JSON做大量的筛选结果和梳理。你自己构建的功能可以集中在与用户所在文档部分最相关的内容上。

你还可以提醒用户注意那些让用户困惑的问题&＃xff0c;比如提供一个工具来探索标题&＃xff0c;或者通过交互式演示突出令牌和秘密的最佳实践。

为开发人员提供选项&＃xff0c;让他们可以绕过第三方工具&＃xff0c;这样你就可以缩小范围&＃xff0c;并将用户的注意力集中在API最重要的功能和需求上。当你让用户直接在你的文档中测试请求和响应时&＃xff0c;你会吸引他们的注意力并缩短他们的启动时间。

文档的目的是让人们成功使用你的 API。提供端点的详细事实记录很重要&＃xff0c;但如果你的目标是推动新的集成&＃xff0c;这还不够。及时了解 API 文档的最新进展。创建一致、可重复使用的交互式文档&＃xff0c;将改善你的开发人员体验。考虑使用API生命周期管理以更快地实现目标。教育和激励你的用户。

本文翻译和演示图片来自Eolink&＃xff0c;更多可自行前往了解&＃xff1a;www.eolink.com使用&＃xff01;