API文档编写示例

采用规范驱动的开发

规范驱动开发 (SDD) 类似于测试驱动开发，其中您为每个功能编写测试用例，然后编写应该通过它们的代码。在 SDD 中，您在构建 API 的同时创建文档或至少其中的某些部分，通常遵循称为规范的特定 API 描述格式。

API文档规范就像是未来文档的模板，是描述 API 设计的统一语言，解释了它的功能以及对它的期望。有一些规范，例如RAML(RESTful API 建模语言)、OpenAPI(以前的 Swagger)和API Blueprint，但有一种趋势是在 OpenAPI 的引擎盖下组合所有规范。

这些规范具有预先构建的文档工具，可用于编写和管理您的文档。例如，API 控制台自动从 RAML 和 OpenAPI 格式生成文档，并帮助您在现有 Web 应用程序上或作为独立应用程序运行它。

作为传统 API 文档解决方案(如 WordPress 或 Drupal CMS)的替代品，API 规范产品是开源的，由开发社区为开发社区创建，具有不同编程语言的解析器，以及持续的创建者支持。

写入门级

技术文档通常不是由开发人员自己编写是有原因的——这是技术作家的工作，是将技术方面翻译成可读格式的专家。但即使是技术作家也倾向于在文本中泄漏一些术语。

API 作为任何软件产品都是为特定受众创建的。但是文档的受众非常广泛。文档用户主要分为三组：

将与文档密切交互的开发人员

决策者，如CTO和解决方案架构师，他们想要快速确定您的 API 是否适合

观察者，例如记者、技术作家，甚至不一定会永远使用您的 API 的竞争对手。

即使在每个组中，都有不同技能、角色和需求的人，他们都应该对文档有积极的体验。你如何针对他们?通过针对经验最少的用户。那么，您如何为新手编写文档?

从机会而不是技术开始。用引人入胜的故事向用户致意，讲述您的 API 如何丰富他们的产品或使开发人员的生活更轻松十倍。

显示从哪里开始。API 文档因过于繁琐和假设用户对 API 拥有丰富的经验而臭名昭著。入门部分是强制性的，应该为潜在用户耐心编写。

为最常见的用例创建说明。您可能已经知道人们将您的 API 用于哪些功能。创建单独的部分来解决它们并在那里包含示例消息。

使用对话的语气。开发人员社区是悠闲和非正式的，因此即使听起来更“专业”，他们也不会欣赏枯燥的公司语言。好的文档总是与人交谈。

教育外部工具。如果您的 API 需要使用和理解第三方产品和概念(如 OAuth 或 npm)，请包含指向文档或安装指南的链接。

让学习变得轻松。API 文档不是宜家组装说明，而是学习资源。在可能的情况下，使用常见问题解答、教程、博客甚至视频来丰富您的文档。

加入必备部分

2019 年，Swagger 的开发者 SmartBear对 API 开发者和用户进行了调查。他们发现了社区中哪些文档功能被认为是最重要的，为我们提供了开发人员想要涵盖的必备文档部分的列表。我们将通过其中一些。

例子。示例通常以代码段的形式呈现，它们足够有用，但可以变得更加实用。例如，包括像在Medium 文档中所做的那样的字段记录，甚至创建一个模拟 API 供开发人员通过进行实际调用来测试和使用。模拟 API 可以通过 URL 或在 GitHub 上轻松共享，如果完成到一定程度的细节，甚至可以在最终产品中使用。

状态和错误。有标准状态代码和特定于您的 API 的状态代码。最好包含您的 API 可能触发的所有错误。错误通常放在文档的专用页面上，但将其中一些直接复制到它们最常出现的端点下是有意义的。

认证。大多数 API 文档都是从身份验证和授权开始的。它应该涵盖有关如何获取 API 密钥和如何对请求进行身份验证的信息，包括可能的错误、令牌过期时间以及对身份验证敏感性的解释(主要是提醒密钥不能共享，以及可以在哪里使用)。

HTTP 请求。在 HTTP 中提供 Web 请求是文档的最低要求。通常假设开发人员知道如何以他们选择的语言发送 HTTP 请求，但有时，API 创建者会包含各种语言的请求。这可以通过 API 规范工具和 API 管理工具(如 Postman)自动完成。

使用行业标准布局

如果您使用的是文档生成器，则布局已经为您确定。大多数 API 文档的外观和感觉都一样。如果您使用过一些，您就会知道如何处理新文档。尽管如此，组织大量数据，使其易于查找和导航仍然是一项复杂的任务。以下是最实用的布局的一些功能。

动态布局。您可以通过其静态文档识别过时的 API。单页甚至 PDF 文档在 2020 年都无法切割。动态文档易于浏览、更新和添加书签。

粘性内容。不，导航栏不会分散注意力，也不会窃取宝贵的屏幕空间。始终保持内容在视线范围内。

三栏布局。不经常使用，这种布局允许您在代码示例的右侧有另一列。当然，这仅在您有大量文本并希望突出显示代码时才有意义，这样用户就不必来回滚动或在选项卡之间切换。

对语法使用对比色。开发人员花费大量时间查看您的代码示例，因此请使它们具有可读性并按颜色区分不同的组件。

保存滚动状态。这是任何开发人员都会欣赏的小细节。您还可以使用锚链接来指定页面的不同部分，以防它们复制 URL。

鼓励反馈。你的文档是你的主要营销工具——如果人们喜欢它们，他们会使用你的 API 而不是竞争对手的 API，并围绕它推动社区。通常的“这个页面有帮助吗?” 消息将让您知道您解决开发人员问题的程度，并且只要您提供反馈表，就会经常使用它。

不要放弃你的文档

过时的文档是 API 用户最大的烦恼。这也是最常见的错误之一。开发人员通常会在推出更新几天后写下更新，有时将自己限制在几句话。发生这种情况是因为没有既定的文档更新流程，而且没有人负责。以下是确保定期和有用的文档更新的方法。

在更新之前准备文档。将其作为启动计划中的一个额外步骤，在您编写好、详细且经过编辑的段落来介绍您的更新之前，不要推出它们。

定期删除不推荐使用的数据。必须经常审查文档，至少每几个月审查一次。用户反馈功能可以让您更早地发现不一致之处，并且应该始终有一名团队成员负责审查它们并对更新做出反应。

使用分析来改进文档。标准 API 分析会告诉您哪些端点使用得更频繁，因此您可以专注于文档的某些部分并提供更有用的信息或创建专门的教程。监控您的 API 用于的用例，因为这将使您扩大价值主张并以更多可能性更新文档。

很棒的 AP​​I 文档示例

有大量好的文档可供探索和学习。除了我们在整篇文章中分享的示例之外，还有一些示例供您欣赏和注意。

中等 API 文档

Medium API 文档不一定遵守我们今天列出的所有规则，但它们非常适合此 API 支持的有限功能 - 在 Medium 上发布和搜索出版物。它们在 GitHub 上共享，内容非常简短但清晰，包含大量示例，每个示例都以代码中提到的所有参数的抄本结尾，包括可能的错误。它非常简单但可靠——所有建议都可以直接在 GitHub 上提出，并且文档会定期更新。

Mailchimp API 文档

Mailchimp 意识到它的大多数受众是营销专业人士，并且使用的语言即使是非技术人员也能理解如何使用其 API。一目了然，每个部分都遵循相同的结构：

端点做什么以及指南将让用户做什么

您需要什么 - 用户必须首先获得的任何访问权限或帐户

每个功能是什么，带有文本描述、多种语言的代码示例，有时还有界面的屏幕截图。

甚至每段代码都有一个复制按钮——非技术人员肯定会喜欢这个细节。

Twilio API 文档

Twilio 拥有著名的优秀API 文档。尽管文档只是 Twilio 共享的所有帮助的冰山一角，但有多种语言的 SDK 和适用于 iOS、Android 和 Web 的示例应用程序。首先，它们遵循三列逻辑，代码直接位于指南右侧。用详细信息和大量链接来解释最简单的操作，以获取更多信息和屏幕截图。还可以通过“评价此页面”按钮以及指向支持团队的链接和 StackOverflow 上的标签来鼓励反馈。

Spotify API 文档

尽管 Spotify 的 Web API 文档非常典型，但它们在其Spotify for Developers平台中有很多附加信息。有基本功能的演示、模拟应用程序、使用 Spotify API 和小部件构建的现场示例、不同编程语言的包装器，当然还有控制台。控制台基本上是一个交互式文档，您可以在其中填写(或示例)数据并实时探索端点。强大的产品和强大的知识库使 Spotify 成为开发人员喜欢与之合作的可靠合作伙伴。

通过上述相信大家对API文档编写示例已经有所了解，大家想了解更多相关知识，不妨来关注一下动力节点的Java开发工具，里面有更多知识等着大家去学习，希望对大家能够有所帮助。