如今，各行各业的组织都认识到投资 API 项目所带来的商业和战略机遇。API 赋能数字化转型，并为工程和商业发展开辟了诸多可能性。
然而，API 经济的增长也要求构建 API 的团队采取新的思维方式。即使是最好的 API 项目，如果最终用户不理解使用 API 的价值，并且没有可用的必要资源来开始使用它，那么它们也将失败。仅仅拥有一个 API 是不够的；您还需要提供出色的 API 开发者体验。
什么是 API 开发者体验？
API 开发者体验是通用用户体验 (UX) 的延伸。它是开发者与您的 API 交互时所有体验的总和。良好的 API 开发者体验不仅仅是技术写作。它旨在提供所有正确的资源，帮助您的最终用户理解并成功使用您的 API。
为什么 API 开发者体验很重要？
在当今的现代软件世界中，普通技术消费者在组织决定实施的工具和平台方面拥有巨大的购买影响力。根据 Forrester 首席分析师 Jeffrey Hammond 的说法，软件团队内部的采用模式正在向开发者倾斜，赋予他们阻碍或帮助解决方案采用的权力。
这意味着软件产品的技术采纳者现在是产品采用和购买的决策者。因此，在当今高度互联和竞争激烈的生态系统中，特别是在 API 经济中，让您的产品易于技术采纳者使用至关重要。
打造卓越 API 开发者体验的秘诀
在提供卓越开发者体验方面，高性能、易于使用的 API 是无可替代的。开发者体验始终始于提供一个团队乐于合作且可信赖的安全集成 API。
提供卓越开发者体验的一个关键组成部分是提供准确且最新的 API 文档。API 文档是成功使用和集成 API 所需的信息。这可以是技术写作、代码示例和帮助更好理解如何使用 API 的示例形式。
如今，一些最知名且被广泛采用的 API 背后的公司正在投资为其 API 提供丰富、人性化的文档。像 Facebook、YouTube、微软、PayPal 和 DropBox 这样的公司——它们使用内部和公共 API 来推动技术协调和战略增长——正在将文档置于其 API 开发者体验的核心。
如何开始您的 API 文档之旅？
为 API 团队提供以文档为核心的卓越开发者体验从未如此触手可及。过去，团队必须依赖静态文档形式——例如 PDF 或手动更新的网页——而现在，有解决方案可以自动化您的文档工作流程，并构建交互式 API 文档，使 API 的使用成为一个顺畅简单的过程。
组织记录其 API 的方式发生了显著变化。这些变化最明显的体现莫过于 API 描述格式（如 OpenAPI 规范（前身为 Swagger 规范））的广泛采用，它为生成美观、交互式 API 文档提供了构建块，最终用户甚至无需将其实现到代码库中即可进行交互。这种自动生成的文档是一个核心资源，您的开发团队可以对其进行定制和扩展，以创建更全面的 API 使用手册。
在本电子书中，我们将探讨提供卓越开发者体验的要素，以及文档在其中所扮演的角色。我们将介绍 API 文档的最佳实践，并探讨您的团队如何使用 Swagger 工具开始编写 API 文档，以及如何在 SwaggerHub 中改进现有文档工作流程。
让我们开始吧！
规划您的 API 开发者体验
成功的 API 需要像公司产品组合中的任何一流产品一样，得到同等的关注和重视。在处理 API 时应用产品管理原则是将您的 API 视为一流产品的第一步。在本节中，我们将介绍规划 API 开发者体验的 3 个重要步骤
- 了解 API 的目标受众
- 了解 API 采用历程
- 将历程映射到正确的受众类型
了解 API 的目标受众
正如我们之前强调的，文档是您的 API 的使用手册。与任何产品一样——是的，API 也是产品——您需要首先了解谁需要使用您的 API 文档。在下图中，您将看到您的 API 文档的潜在受众概览
您的 API 内容和文档最常见的消费者是需要直接集成和使用您的 API 的人，以及希望评估此 API 是否符合其开发和业务战略的人。这些人可以分为两类
- API 用户：希望集成您的服务并寻求使用您的 API 解决特定问题的开发者。
- API 决策者：将评估您的服务并查看它是否解决了战略需求的人员。
当您开始细分 API 的受众时，就更容易理解您需要提供哪种类型的资源以及这些资源应如何呈现。
了解 API 采用历程
您的受众现在将经历发现和评估您的 API 的不同阶段，然后才能完全投入使用您的服务。这个用户流程将您的目标受众从最初的认知引导到最终熟悉并能够舒适地使用您的 API 服务。一个精心设计的 API 将在这一历程的每个阶段都提供最佳的开发者体验。
下图概述了用户在采用您的 API 之前将经历的关键阶段。这些阶段可以简化为四个主要问题：
- 我为什么要使用它？
- 我如何注册使用它？
- 我从何开始？
- 我如何使用它？
请记住，受众可能会重叠，但分解用户历程可以帮助您确定一个起点，以了解如何与参与采用您的 API 的不同人员进行沟通。
这些阶段也涉及到您组织内不同的角色。例如，前两个阶段更像是产品营销工作，专注于传达您的服务价值以及它们如何缓解现有潜在客户的挑战。当然，接下来的两个阶段纯粹是技术写作工作，技术撰稿人需要制作内容来帮助您的最终消费者理解并集成您的服务。
让我们深入了解这些不同的阶段。
“我为什么要使用您的 API？”
此阶段旨在以一种能立即与受众希望完成的任务产生共鸣的方式，向他们提供您的服务概览。API 用户和评估者应迅速理解您的 API 所提供的价值以及他们如何开始使用它。这是目标受众首次与呈现的信息互动。为了以简单有效的方式呈现这些信息，您需要了解这些潜在客户为何使用您的 API，他们如何发现您的服务，以及您的服务可以帮助解决哪些现有问题。以下是两家做得很好的公司示例：
“我如何注册？”
一旦您说服了 API 用户和决策者，让他们相信您的服务对他们有价值，他们就会继续他们的旅程。注册过程是进入您的 API 服务的第一个步骤。这个过程应该尽可能简单明了，但您也应该能够获取有效管理这些用户所需的信息。一种策略是允许开发者使用流行的第三方服务（如 Twitter 或 GitHub）注册。通过这些服务，可以轻松快速地获取联系信息，而无需让他们经历太多障碍。
如果您确实需要包含额外的步骤才能让人们注册访问您的 API，请务必提供全面的文档和帮助提示以加快流程。糟糕的开发者体验的一个例子是强制用户填写冗长的表格，或者在提供 API 密钥之前要求不必要的详细信息。
“我从何开始？”和“我如何使用它？” 
既然目标受众已经注册访问您的 API，下一步就是让他们开始使用。
这些是您的开发者使用 API 服务的旅程的最后阶段。他们希望亲自动手操作您的 API 代码，进行尝试，并最终将其集成到自己的应用程序中。
引导他们完成这一旅程的秘诀是什么？
出色的 API 文档。
文档是良好开发者体验的核心
对于希望推动其 API 采用的组织而言，简洁明了的文档——能够让您的 API 用户快速将其集成到自己的应用程序中——已不再是可选项。
请考虑以下几点
- 根据 SmartBear 的 2016 年 API 状况报告，75% 开发 API 的组织现在都拥有正式的文档流程。46% 的组织表示这是其高度优先事项。
- ProgrammableWeb 的一项调查发现，API 消费者认为完整且准确的文档是影响其 API 决策的最大因素，甚至超过了价格和 API 性能。
良好的文档可以加速开发和使用，并减少原本用于接听支持电话的资金和时间。重要的是要记住，文档对于内部 API 用户也同样重要。不要以为您的内部利益相关者会非常熟悉如何使用 API。
您的 API 文档中应该包含哪些内容？以下是一些在编写 API 文档时可能对您有所帮助的提示。
提示 #1：列出基本要素
每个良好的 API 文档都必须包含某些部分。没有这些部分，用户将很难理解如何使用您的 API。
- 认证。这是您的用户开始使用您的 API 所需的认证方案信息。例如，如果您使用 OAuth，请不要忘记解释如何设置 OAuth 应用程序并安全地获取 API 密钥。
- 错误消息。错误消息很重要，因为当您以不正确的方式集成 API 服务时，您希望获得反馈。解释您的错误标准，并提供解决方案，说明当最终用户遇到错误时如何解决它们。
- 端点以及如何使用它们的信息。注意描述您的请求和响应周期。这些是您的 API 的主要组成部分，用户将与您的服务进行交互，因此请密切关注这一点。
- 使用条款。这是消费者与您的组织之间的法律协议，定义了消费者理想情况下应如何使用您的服务。这很重要，因为您希望确保开发者和消费者遵守您组织的推荐实践，并且不做任何违背您商业价值观的事情。
- 在最佳实践中包含 API 限制，并附带条款和条件。限制也需要明确说明，以便消费者了解允许哪些 API 用法和实践。
- 更新日志。详细说明 API 的更新和版本以及它们可能如何影响 API 用户。这将帮助用户了解 API 的稳定性，并查看是否需要进行任何更改以实现有效的 API 调用。一旦您列出这些部分，就可以轻松地进行文档编写，因为您的 API 已经有了一个良好的开端。
提示 #2：为人编写
大多数 API 文档编写者假设其文档的受众是 100% 的开发者，或者对如何使用 API 拥有充分技术理解的人员。但请记住，许多使用 API 的人可能对您正在使用的领域或行话不甚了解。文档应该迎合 API 用户（通常是开发者）以及技术水平相对较低的 API 评估者（通常是产品经理和 CTO）。
在编写文档时，首先为每个调用提供英文领域的解释。避免使用过多的技术术语，并以易于 API 新手理解的方式进行编写。
如果您确实有技术或领域特定的术语，请将该特定项目链接到进一步解释这些术语的文档。这些策略将确保您的 API 清晰且结构良好，并解释某些调用存在的原因，在您陷入参数、标头和响应的细节之前。
请看 Stripe API 文档中的这个例子。他们出色地做到了通过额外的内容来解释其所有的技术术语。
提示 #3：解释您的请求-响应周期
您的 API 用户应该清楚地知道成功的 API 调用会返回什么。描述所有支持格式的完整示例响应体。不仅要考虑格式，如 XML 或 JSON，还要考虑 HTTP 标头、错误代码和消息。为最终用户提供过多的信息不会成为问题，特别是当他们试图将您的服务集成到其应用程序中时。
为您的 API 应返回的每一个对象提供示例，并提供用户可以添加的参数示例以实现成功的 API 调用。这是 Stripe 的另一个例子。最终用户可以很容易地从文档的开头准确理解每个错误代码的含义。
提示 #4：实验就是力量
除了基本文档之外，团队还应提供其他资源，以增强他们为最终用户提供的体验。
- 入门指南：“入门指南”可以成为已决定实施您的 API 的开发者的一个有用下一步资源。此资源应提供更详细的关于如何快速使用 API 的分步说明。
- 交互式文档和控制台：您的受众会希望在将 API 直接集成到其应用程序之前先试用它。提供一个沙盒或控制台，让开发者可以轻松地为不同的端点部署和重置响应，而无需修改源代码。
- SDK：一旦您的 API 发布，投资构建允许最终用户有效使用您的 API 的客户端库是一个好主意。如果许多开发者发现您的服务有价值，他们甚至可能为您构建 SDK。提供良好的开发者体验是培养您的开发者社区的好方法。
- 教程：提供示例代码片段、示例 SDK 和良好的用例，以帮助用户理解您的服务。
使用 OpenAPI 进行 API 文档编写
如今，全球数千个 API 团队使用 OpenAPI 规范 (OAS) 和 Swagger 工具为其内部和面向公众的 API 生成文档。
OpenAPI 规范概述
OpenAPI 规范是一种机器和人类可读的描述格式，它定义了 API 的契约。该契约定义了资源和服务公开哪些数据，以及客户端应如何调用这些资源。虽然这个想法看起来很简单，但它在多平台 API 经济中具有强大的影响力，在多平台 API 经济中，服务以多种语言构建，并由不同设备上的客户端使用。
2015 年 SmartBear Software 捐赠该规范时，它从 Swagger 规范更名为 OpenAPI 规范。它已成为 REST API 设计和文档化的行业标准。将 OAS 实施到您的 API 工作流程中有很多实际用途，其中 OAS 最常见的应用是为 API 团队生成美观的交互式文档，这些文档可以轻松地与 API 的最终用户共享。
OAS 解决了团队在处理 API 文档时面临的两个最大挑战：
1. API 文档的维护
为您的开发团队和最终用户维护和更新文档，以便他们能够高效地使用您的 API，可能是一个困难而乏味的过程。如果您使用静态文档（如 PDF）向最终用户提供文档，情况尤其如此。OAS 允许您为您的 API 定义一个契约，并使用 Swagger UI 或 SwaggerHub 等工具为该 API 自动生成交互式 UI。
该交互式 UI 可以作为您团队的画布，用于构建 API 文档，其中包含出色的 API 文档所需的各种示例、描述、错误消息和其他详细信息。
2. 多服务交互
API 需要一个通用的接口，用于不同服务之间的使用和交互。传统的 API 接口，无论是文本文档还是 Javadocs 等其他形式，都不允许不同语言的服务之间进行交互。
使用 OAS 定义的 Web 服务可以相互通信，无论它们是用何种语言构建的，因为它与语言无关且机器可读。
使用 OAS 编写您的 API 文档
使用 OAS 编写您的 API 文档 首先要生成一个初始的 OAS 契约或“规范”，它构成了您 API 设计和文档的基础。以下是该契约的示例
openapi: 3.0.0
info
title: 示例 API
description: 可选的多行或单行描述，支持 [CommonMark](http://commonmark.org/help/) 或 HTML 格式。
version: 0.1.9
servers
- url: http://api.example.com/v1
description: 可选的服务器描述，例如：主（生产）服务器
- url: http://staging-api.example.com
description: 可选的服务器描述，例如：内部测试服务器
paths
/users
get
summary: 返回用户列表。
description: 可选的扩展描述，支持 CommonMark 或 HTML 格式。
responses
'200': # 状态码
description: 一个包含用户名的 JSON 数组
content
application/json
schema
type: array
items
type: string
生成 API 的 OAS 有两种方法
- 设计优先： 首先制定 OpenAPI 规范，并将其转换为人类和机器可读的契约（例如 OpenAPI 定义），然后在此基础上构建代码并生成文档。
- 代码优先： 根据业务计划，直接编写 API 代码，然后从中生成人类或机器可读的文档（例如 OpenAPI 定义），接着即可进行文档编写。
这两种方法各有利弊，归根结底，选择正确的方法取决于您希望通过 API 解决的即时技术和战略需求。
虽然设计优先的方法正在兴起并获得越来越多的采用，但如今大多数组织仍然遵循代码优先的方法。由于文档对于最终用户的重要性，这些组织将使用第三方工具从其现有 API 生成 OpenAPI 定义，然后利用该 OpenAPI 定义，利用像开源 Swagger UI 或 SwaggerHub 这样的工具来生成交互式 API 文档。
为了帮助简化该流程，Swagger 团队最近发布了一款用于生成 OAS 定义 的新工具——Swagger Inspector。Swagger Inspector 是一款易于使用的开发者工具，可以快速执行任何 API 请求，验证其响应，并生成相应的 OpenAPI 定义。
让我们从使用最新的 Swagger 工具之一 Swagger Inspector 来看看代码优先方法如何运作。
使用 Swagger Inspector 生成 OpenAPI 定义
使用 Swagger Inspector，通过调用每个端点并选择相关响应来生成符合 OAS 的文档，或将一系列调用串联起来为多个 API 端点生成完整的 OAS 文档，从而快速为您现有的 REST API 生成基于 OAS 的文档。
无论您的团队对 Swagger 采取何种方法，您都需要开展工作来构建您的 API 文档。在大多数情况下，组织将依靠技术撰稿人来完善文档。这包括添加有意义、易于理解的信息，您的最终用户可以使用这些信息来实现 API 的成功。 从该契约中，可以使用 Swagger UI 生成交互式版本的文档。Swagger UI 允许任何人——无论是您的开发团队还是您的最终用户——在无需任何实现逻辑的情况下可视化并与 API 的资源进行交互。
拥有 Swagger Inspector 账户，您还可以自动为您调用的任何端点生成 OpenAPI 文件，从而节省开发时间。Swagger Inspector 与面向团队的 API 设计和文档平台 SwaggerHub 紧密集成。该集成允许开发者在 SwaggerHub 上自动托管和可视化其 API 文档，从而使内部和外部利益相关者能够发现和使用 API。
请按照以下步骤开始操作。
如何从现有 API 生成 OpenAPI
前往 Swagger Inspector，请求您希望记录的资源的一个或多个端点。然后，导航到 Swagger Inspector 右侧的“历史记录”面板，点击“创建 API 定义”以创建 OAS 定义。
Swagger Inspector 的一大优点是其集合功能。选择多个端点，并通过集合将它们的文档整合到一个 OpenAPI 文件中。
如果您已有 SwaggerHub 账户，则可以使用这些凭据登录 Swagger Inspector。
生成的定义将为您的团队提供一个符合 OAS 的结构，以构建您的 API 文档。有了该定义，您可以添加重要细节，例如：支持的内容类型、描述、示例、身份验证类型等
接下来，我们将详细介绍如何在 SwaggerHub 中，利用此定义继续构建您的 API 文档。
使用 SwaggerHub 增强 API 文档
正如我们上面详述的，API 文档编写绝非易事。组织不仅需要进行技术写作，还要确保文档安全且易于使用。还存在托管和维护等运营考虑因素，所有这些都会给组织带来额外的资金和时间开销。
这就是为什么像 SwaggerHub 这样专业的组织平台能够提供帮助的原因。SwaggerHub 是一个集成的 API 设计和文档平台，专为团队打造，旨在推动 API 开发工作流程中的一致性和规范性。
SwaggerHub 的交互式文档将您的 OAS 定义可视化呈现，以便进行实时交互和操作，从而使您的最终用户在将其集成到其代码库之前，就能清楚地了解您的 API 将如何读取和行为。
它直接从 API 契约生成，该契约可以使用 SwaggerHub 编辑器从头创建，或从您的文件系统和源代码控制主机导入。
在 SwaggerHub 中有几种不同的入门选项。如前所述，您可以利用 Swagger Inspector 生成 OAS 定义并将其导入 SwaggerHub。
如果您正在启动一个新的 API 项目，SwaggerHub 编辑器使您可以轻松开始设计新的 API。让我们看看一些可以帮助您的团队入门的功能。
实时可视化渲染
SwaggerHub 提供了一个强大的可视化编辑器，用于使用 OAS 定义您的 API 的每个端点，使 API 架构师和开发者在编写任何代码之前就能了解消费者将如何与您的 API 交互。SwaggerHub 将文档置于您的 API 工作流程的中心，让您可以为您的 API 自动生成交互式 UI，该 UI 会随着 API 契约的每次更改而更新。
安全、自动托管
SwaggerHub 消除了设置后端服务器来托管 API 文档的需要。SwaggerHub 允许您在一个集中平台上托管您的文档，并轻松地为您的 API 开发团队或最终用户提供受控访问。您可以从 SwaggerHub 内部公开文档，或将其设置为私有并邀请内部团队成员或合作伙伴进行安全共享。
优化、无困扰的工作流程
您的 API 设计和文档涉及多个利益相关者，而良好的协作是成功发布 API 的关键。 通过严格控制添加到主 API 工作流程中的更新，更好地协同工作。协作者可以通过派生主 API 来创建副本，添加更改，并通过可视化比较和合并功能将更改合并回主 API 工作流程中。随着您的 API 发生变化，您的团队会立即收到发送到其收件箱的电子邮件通知。
快速启动的 API 开发者门户
您的 API 开发者门户是卓越开发者体验的自然延伸，其中包含文档和代码片段，以帮助最终用户理解和使用您的 API。利用 SwaggerHub 内置的 HTML 门户生成器，为您生成开发者门户的基础客户端代码，供您在此基础上进行构建。只需一键，SwaggerHub 即可为您的开发者门户生成 HTML 模板，其中包含您的 API 文档和 6 个客户端 SDK 使用示例，使您的开发团队能够非常轻松地进行自定义、交互和使用。
维护和迭代
组织可以集中维护其所有 API 文档及其相关版本。在现有 API 文档的基础上逐步构建，或者使用 SwaggerHub 的版本控制系统维护生产环境中多个 API 版本的文档。通过在现有版本上构建，发布稳定、可用的 API 的文档，并优雅地弃用过时版本。
通过出色的 API 文档提升开发者体验
请记住，文档是您的 API 的使用手册，也是实现 API 业务目标的最大驱动力之一。OpenAPI 规范和 Swagger 工具消除了文档方面的顾虑，创建了交互式、人类和机器可读的文档，这些文档是自动生成的，并且只需要最少的维护。
创建您的用户喜爱的 API 文档需要付出努力，但这项投资将带来巨大的回报，体现为卓越的开发者体验、更简单的实现以及更高的 API 采用率。
SwaggerHub 消除了所有基础设施和安全实施方面的顾虑，使组织能够无缝协作，并创建深受用户和开发团队喜爱的出色 API 文档。
超过 150,000 名 API 开发者和组织信任 SwaggerHub 来帮助改进他们的 API 文档工作流程。
了解 SwaggerHub 如何帮助您的团队。立即免费开始使用。