原文链接：https://document360.com/blog/api-developer-portal-examples

开发者门户是什么？

DevPortal 奖的主要赞助商 Provonix 对开发者门户的定义如下：

“开发者门户（通常缩写为 DevPortal）是一组 API、SDK 或其他交互式数字工具与其各种利益相关者之间的接口。”

更直白地说，开发者门户是为公司提供的所有服务接口和解决方案的网站。它们是许多利益相关者的资源，而不仅仅是开发者的资源。

普通官网和开发者门户之间的一个主要区别是，普通网站是静态的内容，而开发者门户包含不断更新的动态内容。

与 wiki 不同，开发者门户是对外的，同时也作为内部利益相关者的资源。由于维基是内部的，所以当优先级从文档转移时，它们往往会被忽视并逐渐过时。由于开发者门户是对外的，因此与内部维基相比，其维护的优先级通常更高。

调查强调了高质量开发者文档的重要性。SmartBear 发布的《2019 年 API 状况报告》中的一项调查将**“准确详细的文档”**列为 API 的三大特点之一。开发者门户是 SaaS 公司共享文档的主要方式。

开发者门户和营销网站之间的关系也较为模糊。有时，一家企业会拥有一个链接跳转到其开发者门户的营销网站。而像只提供 SaaS 服务的公司等其他公司则会有开发者门户，但却没有专门的营销网站。

开发者门户的意义是什么

那么为什么公司应该投入时间和金钱来加强其开发者门户呢？一个好的开发者门户能够传递平台及其服务的价值。它描述了它们如何解决特定的业务挑战，而不是使用夸张的营销/广告。

虽然 API 文档经常与开发者门户相关联，但开发者门户不仅仅是开发人员访问其 API 参考文档的地方。开发者门户应该允许所有业务利益相关者（技术或非技术）了解和体验平台。

在下一节中，我们将探讨这些特性。

一个好的开发者门户的特点

统一解决方案

虽然 API 文档是开发者门户的一个重要方面，但它并不是全部。理想情况下，开发者门户应该作为公司产品和服务所有接口的中央资源。它们可能不仅仅局限于 API/服务。其他接口还包括图形用户界面（GUI）、无代码界面以及像面向没有访问开发者资源用户的小组件这样的低代码界面。

虽然 REST API 规范是开发者门户的重点，但也可以记录其他类型的 API，如物联网（IoT）API、语音助手 API、GraphQL API 或原生库 API。通常公司会有一系列服务，而不仅仅是一个 REST API。你可能会在开发者门户上看到数十种不同类型的 API 文档。除了 API 之外，开发者门户上提供的其他技术解决方案还包括客户端库或 SDK。有时，开发者门户还可以展示开发者构建的解决方案。

明确的商业模式

用户应该能够理解平台所在的行业及其提供的服务的广泛概述。解决方案应该根据它们解决的特定业务挑战进行分类。用户应该能够在心理上绘制出所有提供的解决方案以及它们如何在统一平台上协同工作的地图。

服务如何在更广泛的上下文中相互关联，可以通过文本、视觉图形或开发者门户本身的结构来传达。

明码标价

客户应该尽早了解平台的定价模式。定价结构应该传达它是如何解决特定问题的以及定价计划之间的差异。

开发者门户应该回答以下问题：

• API 产品是如何实现货币化的（直接 vs 间接）？
• 可用的定价计划有什么区别？是否有即用即付、自助服务或免费增值计划？
• 每个定价计划是否有任何速率限制？
• 定价计划与注册过程相关，因为用户通常在被要求付费之前只能使用有限数量的功能。透明的定价有助于潜在客户转变为实际客户。

内容“分层”

分层架构是一个从软件开发中借鉴的概念，也可以应用于内容组织。

以下是一个开发者门户可以如何分层的例子：

• 开发者门户的顶层是用户了解商业模式、服务/解决方案概述和常见用例的着陆页。
• 中间层是解决方案类别，根据它们解决的业务挑战对解决方案进行分组。
• 底层是这些解决方案的文档，包括任何入门教程和 API 参考。

当然，这些只是示例。根据实际业务需要，可能还需要其他层。分层架构允许解决方案之间保持一致性。用户了解到每个部分应该期待哪些信息。

类似于主着陆页，每个解决方案都应该有自己的着陆页，传达该解决方案的价值。解决方案页面提供快速访问解决方案概述、用例、注册详情、入门指南和技术参考资料。

使用将平台的不同组件分开的分层架构允许广泛使用链接。你可以从业务部分链接到技术部分，反之亦然。例如，阅读解决方案概述的业务分析师可能只想查看业务信息，同时也有办法通过点击链接了解更多技术文档。链接还允许开发者跳转到技术细节，而不是被困在阅读业务材料中。

一致的设计

设计元素如果处理得当，就超越了美学的范畴。设计元素可以促进可用性，并与内容的质量相辅相成。一个设计良好的开发人员门户应当具有支持用户查找、了解和与平台交互的设计元素。有效的设计将强化整体品牌。一个品牌不仅决定了审美的选择，而且还决定了内容是如何书写的。文档应该在所有解决方案中使用相同的风格和基调并保持一致。

可查找性

用户能够轻松发现解决其业务挑战的方案是开发者门户的主要目标。在开发者门户上查找信息的过程应该是顺畅的。

开发者门户中信息的“可查找性”由其结构和搜索/过滤功能决定。开发者门户应该以用户可以轻松看到可用解决方案范围的方式组织其文档门户。用户应该能够轻松按类别过滤解决方案，以缩小可能性列表并消除噪音。

从API参考中，你应该能够按资源、端点、参数和模式搜索和过滤。

迎合非技术用户

SaaS 公司也明白，除了从头开始构建一个利用服务的应用程序之外，还有不同的方式来使用技术产品。例如，一个平台可能提供小组件，你可以轻松地将它们添加到你的网站中，几乎不需要编码。零代码或低代码解决方案打破了谁可以体验技术产品价值的障碍。

最好的开发者门户为每个能力水平都提供了注册流程。例如，技术用户可以从头开始构建一个应用程序，而非技术用户可以下载模板开始体验。

注册流程

用户注册流程通常是用户首次使用解决方案的体验。如果注册过程中存在卡壳，潜在客户可能会在完全演示 API 之前放弃。在设置账户并检索凭据后，“入门”部分将引导用户完成与 API进行交互的过程。

API 参考

API 参考是给开发者阅读的简洁而详细的指南，用以了解 API。有效的 API 参考页面允许开发者通过搜索和过滤的组合快速定位资源、端点、字段或模式的信息。

试用功能提供了一种与 API 进行交互的实践方式。最先进的 DevPortals 会根据用户的账户详情，自动在试用小工具中填充用户的凭据。

社区

社区通常是故障排除问题的第一级支持。许多开发者门户都有社区页面。一些公司使用像 Discord 频道或公共 Slack 频道这样的工具，在不同类别下主持讨论。

如果用户可以通过在留言板上发布问题来找到答案，他们就不需要联系支持人员。如果公司参与社区，它可以将问题记录为错误或文档改进。

社区可以超越只是讨论论坛。它们可以促成小型会议或大型会议，以推广平台。

更新

随着平台的不断发展，定期发布更新是可靠性和可信赖性的标志。发布说明、法令和变更日志都是补充文档的例子，它们让用户了解最新变化。

开发者门户最佳实践

在编写任何代码之前，构建开发者门户有许多步骤。假设商业模式是稳定的，应该进行开发者体验（DX）设计，以使门户的所有方面都与为用户提供最佳体验相一致。

明确商业模式

社区通常是故障排除问题的一级支持。许多开发门户网站都有社区页面。有些公司使用 Discord 频道或公共 Slack 频道等工具来主持不同类别的讨论。

如果用户可以通过在留言板上发布问题找到答案，他们就不需要联系支持人员。如果公司参与到社区中，就可以将问题记录为错误或文档改进。

社区可以不仅仅是论坛。它们可以促成小型会议或大型会议，从而推广一个平台。

进行开发者体验（DX）设计

开发人员门户网站与开发人员体验（DX）的概念密切相关。与一般的用户体验设计不同，DX 是为开发人员量身定制的，他们使用的技术产品通常没有图形用户界面，如应用程序接口、客户端库或 SDK。由于没有用户界面，文档必须告诉开发人员如何与产品对接。文档在很大程度上对开发人员或其他业务利益相关者如何 “体验 ”技术产品起着重要作用。

与公司聘用用户体验设计师的方式相同，他们也应该聘用 DX 设计师来精心设计开发人员使用 DevPortal 的体验。DX “指导”是管理开发人员门户生命周期的核心角色。DX 指导负责监督流程、标准和工具的变更，这些变更会流向各个解决方案团队。这位指导要确保设计、美学、结构和内容相互配合，为开发人员创造愉悦的体验。

指导将为访问门户网站的用户创建角色，并精心设计用户旅程以满足他们的需求。例如，技术用户和非技术用户最好有不同的入职用户旅程。

构建门户结构

在建立信息架构时，你必须确定所有解决方案都需要哪些信息。例如每个解决方案都需要按特定顺序进行入门、用例和 API 参考。如果文档在解决方案之间是统一的， 开发者门户的用户就知道该期待什么。

分层架构与链接相结合，将使从顶层（业务细节）到底层（技术细节）的导航变得更加容易，反之亦然。

建立治理程序

很多时候，每个解决方案由不同的团队管理。为了在门户中提供一致的体验，必须建立促进内容组织一致性和写作指南的标准。

建立治理程序需要协作来制定标准，以及来自不同业务部门的买入，以完全完成程序。每个团队都应该负责遵守这些标准并被问责。治理程序应该对齐语言和语气、风格和格式，并组织从业务材料到 API 参考的内容。最后，治理程序应该加强品牌。

通过入门教程减少学习曲线

在传达了整个业务的价值之后，用户应立即被引导到他们可以尝试 API、服务、客户端库或 SDK 的单独解决方案页面。这些页面的前端和中心应该是一个链接到入门程序的链接，以便他们尽快体验产品。

对于入门教程，请选择一个简单的使用案例，用户可以按照这个案例从头到尾了解解决方案。

适当记录 API 参考

所有的 API 组件是否都已经被准确地记录了？每个资源是否都已被记录？各个端点和模式是否都已被充分描述？每个字段的描述是否都清楚地说明了它的目的、选定值的影响，以及它与系统中其他字段的交互？相同字段的定义在整个规范中是否都是一致的？

API 参考的内容应遵循一个 API 样式指南，该指南规定了 API 所有组件的标准。遵循这个样式指南将确保 API 参考的一致性和完整性。没有准确和详细的参考信息，所有的高级功能都是无用的。

记录技术参考信息通常是改进整体文档的第一步，因为在编写教程之前，技术信息必须是稳定的。

支持搜索/过滤

开发者门户可能有对应于不同解决方案的数十个页面。除了清晰的网站结构外，拥有强大的搜索可以提高可发现性，以便用户可以找到解决其特定业务问题的解决方案。

应该有 API Explorer，用户应该能够在提供的解决方案列表中进行搜索和过滤。

在 API 参考文档中拥有强大的搜索功能很重要。API 参考上的搜索栏应允许对构成 API 的所有组件进行细粒度搜索。

建立社区

从早期开始，您应该考虑如何培养和增长围绕您业务解决方案的社区。这既是支持的长期策略，也是产品采用的策略。

社区的其他更微妙的形式是要求开发人员注册新闻通讯，以保持通信畅通。

启用反馈机制

开发者门户上应该有很多位置让用户提供反馈。例如，每个 API 参考部分都提供了评分机制，并有提供自由填写反馈的选项。

反馈的另一个来源是社区。一个积极使用产品的社区是一个反馈的来源，甚至不需要去要求用户来反馈。

提供案例研究和参考

当案例研究与已使用产品的客户的推荐相结合时，它们是更有说服力的的。案例研究可以是常见的商业挑战以及如何使用平台解决这些挑战。用户可能会与案例研究产生共鸣，并立即看到他们如何使用该工具来完成特定任务或解决其他人遇到的某个问题。

定期发布更新和状态

随着平台的发展定期发布更新是可靠性和信任度的信号。

最佳的开发者门户案例

以下是按类别划分的最佳开发者门户。

最佳 API 参考：Stripe

Stripe 是一个支付处理平台，拥有设计良好且直观的API参考文档。

API 参考文档必须允许开发者在技术细节的海洋中快速找到他们需要的信息。

Stripe 是一个单页网站，您可以通过单击左侧导航链接、滚动页面或执行搜索来快速导航至不同部分。

Stripe 的一些 API 参考功能包括：

• 可折叠内容?– 几乎所有内容都是可折叠的，包括字段描述、表格、模式等。这样您可以专注于您需要的信息，而不会有多余的杂乱。
• 可切换的编程语言?– 您可以一键全局更改代码示例的编程语言。还可以通过单击复制到剪贴板按钮轻松复制代码样本。
• 开发者友好的暗模式?– 对于喜欢看起来像代码编辑器的暗色背景的开发者来说，这是一个很棒的功能。
• 广泛的链接?– 每当需要深入解释时，API参考都会提供指向概念性文档的链接，以获取背景信息和教程。
• 多个反馈点?– 您可以为每个部分提供反馈，包括在给出评分后编写自由形式的文本。
• 高级搜索和过滤?– Stripe 的高级搜索允许您对 OpenAPI 的几乎所有组件进行字段搜索。

最佳可查找性：Visa

Visa 开发者平台让您能够通过 API 利用 Visa 网络的强大功能，。

该平台脱颖而出的点在于它有非常易用的筛选功能，便于找到你需要的一个 API 和服务。您可以通过几个类别过滤 API 列表。过滤允许您快速定位解决您特定业务挑战的 API。

在过滤后的列表中，每个 API 产品卡片包含服务的简短描述，然后是指向API的概述或文档页面的链接。概述包含一般业务信息，而文档包含API参考。然后，您可以根据是需要入门还是希望查看技术参考，快速找到所需的文档。

此外，您还可以从包含推荐和案例研究的使用案例页面找到适用于您情况的使用案例。

最佳代码教程：Fiserv

Fiserv的开发者门户在提供如何实现Fiserv API的逐步示例方面表现出色。

“食谱”（Recipes）是针对不同用例的教程，包含各种语言的代码示例。每个食谱都会引导你完成一个特定的任务，并且过程中的每一步都有注释来提供更多上下文。

当从主要文档中访问这些食谱时，它们尤其出色。每当需要分步指南时，主要文档都会链接到特定的食谱。这种将代码示例集成到文档中的方式使Fiserv的平台非常以用例为导向。

最适合非技术用户：platformOS

platformOS 是一个强调性能、可靠性、灵活性、安全性和可扩展性的“平台即服务”开发平台，具有许多用例。

platformOS 是易用性很高的的平台之一，因为它迎合了所有技术水平的用户。它将用户分为三种不同类型：非技术用户、半技术用户和技术用户。每种用户类型都有自己的入门旅程。

• 非技术用户?可以单击一键安装注册账户，并按照一个简单的设置向导创建一个演示博客站点。
• 半技术用户?可以单击沙盒链接从 GitHub 克隆一个演示站点。然后，他们可以按照 Hello, World! 指南了解发送请求和读取响应的基础知识。
• 技术用户?可以通过单击构建您的第一个应用直接使用 platformOS 平台创建一个应用。他们可以按照文档设置开发环境，然后部署和测试他们的应用。

platformOS 支持非技术人员体验平台，同时为技术用户提供了快速途径以实现从零开始构建应用。

总结

很多 SaaS 公司正在大力投资他们的开发者门户。这些公司现在认识到 开发者门户上的内容作为影响采用的外部资源的潜在高价值。创建一个有效的开发者门户需要整个组织的一致性和自上而下的治理程序来加强品牌。

更多 API 管理及 API 全生命周期相关内容可以在我的 Notion 查看，我将会持续更新：API 全生命周期管理资料