实用性开发者门户构建实践指南

一、什么是开发者门户？

开发者门户（或者 API 开放门户，或者叫API 开放平台）简称 DevPortal/API DevPortal，是 API、SDK 或其他交互式数字工具与各类利益相关者之间的接口。简单来说，开发者门户是提供公司服务和解决方案接口的网站。它是多种利益相关者（不仅仅是开发者）的资源。

开发者门户与普通网站的主要区别在于，普通网站包含静态内容，而开发者门户包含动态内容，这些内容不断更新。

开发者门户不像内部的 wiki 那样局限于公司内部，而是外部资源。由于 wiki 通常随着优先事项的变化而被忽视，导致内容过时。而开发者门户作为外部资源，通常被优先维护。

根据市场上调查显示，高质量的开发者文档非常重要。比如 SmartBear 的《2019 年 API 状况报告》显示：“准确且详细的文档”在 API 的重要特性中排名第三。开发者门户是 SaaS 公司分享文档的主要途径。

开发者门户与营销网站之间的界限也模糊不清。有些时候，企业会有一个营销网站链接到其开发者门户，而一些 SaaS 公司则只有开发者门户，而没有专门的营销网站。

二、开发者门户的重要性

那么，为什么建议互联网企业组织都应该投入时间和资金来提升其开发者门户？因为一个优秀的开发者门户可以传达平台和其服务的价值，展示如何解决特定的业务挑战，而这种“实在”是使用营销或广告的夸大言辞所无法达到的。

虽然 API 文档经常与开发者门户相关联，但开发者门户不仅仅是开发者访问其 API 参考文档的地方。它应允许所有业务利益相关者（无论技术水平如何）都能够了解并能体验得了平台。

---

三、开发者门户建设指引

在写代码之前，构建开发者门户需要经过许多步骤。假设商业模式稳固，开发者体验设计应协调门户的各个方面，为用户提供最佳体验。以下总结了一个优秀开发者门户（API 开放平台）的建设指引，欢迎大家借鉴。

3.1 要为用户提供统一的解决方案

虽然 API 文档是开发者门户的重要部分，但它并非全部。理想的开发者门户应成为公司所有产品和服务接口的中央资源，不仅限于 API 或服务。其他接口包括图形用户界面（GUI）、无代码接口和低代码接口，例如为没有开发资源的用户提供的小组件。

除了常见的 REST API，开发者门户还可以记录其他类型的 API，如物联网（IoT）API、语音助手 API、GraphQL API 或本地库 API。公司可能拥有多个不同类型的 API，在开发者门户上看到几十种 API 是可能的。除了 API 外，开发者门户还可以提供客户端库或 SDK。有时，开发者门户还会展示开发者构建的解决方案。

3.2 具备明确的商业模式

一个成功的开发者门户需要具备清晰的商业模式，帮助用户全面理解平台所处的行业及其提供的服务概况。解决方案应根据具体的业务需求进行分类，并通过文本、图示或门户结构等方式展现，帮助用户建立平台解决方案的整体认知，清楚了解各方案在平台内的协同关系。

清晰的定价-用户应能尽早理解平台的定价模型。定价结构应传达其如何解决特定问题，以及各定价方案之间的差异。

开发者门户应回答以下问题：
API 产品是如何变现的（直接 vs. 间接）？
各种定价方案的区别是什么？是否有按需付费、自助服务或免费模式？
各定价方案是否有速率限制？

定价计划与用户的入门流程有关，通常允许用户在付费前体验部分功能。透明的定价有助于潜在客户转化为实际客户。

3.3 合理的结构分层与体验设计

1）门户结构

门户的结构应准确反映业务逻辑和解决方案架构。如果这一点无法清晰传达，用户在使用过程中可能会感到困惑。为了保持门户的持续更新，这不仅仅是某个团队的责任，而是需要全组织的协同合作。各团队必须承担起更新各自内容的责任，及时对用户反馈作出响应，确保平台信息始终保持准确和最新。

建立信息架构时，必须确定所有解决方案所需的信息。例如，每个解决方案都需要按特定顺序提供入门指南、用例和 API 参考。如果文档在所有解决方案中统一，开发者门户的用户会知道应该期待哪些内容。

分层架构加上链接将使从顶层（业务细节）到底层（技术细节）或相反方向的导航更加容易。

2）内容分层

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

例如，开发者门户可以这样分层：

顶层：开发者门户的首页，用户可以理解商业模式、服务/解决方案概述以及常见用例。
中间层：根据解决的业务挑战对解决方案进行分类。
底层：提供这些解决方案的文档，包括入门教程和 API 参考。

这种分层架构确保解决方案之间的一致性。用户能够在各部分中知道应期待哪些信息。

每个解决方案应有自己的登录页面，快速提供解决方案概览、用例、入门详情、教程和技术参考材料。通过分层架构可以广泛链接，技术用户可以跳转到详细技术文档，业务用户则可以保持在更高层次的内容中。

3）打造更适合开发者体验

开发者门户与开发者体验（DX）的概念紧密相关。与普通用户体验（UX）设计不同，DX 针对开发者，他们经常使用没有图形用户界面的技术产品，如 API、客户端库或 SDK。由于没有用户界面，文档必须告诉开发者如何与产品交互。文档在开发者或其他业务利益相关者“体验”技术产品时起着至关重要的作用。

与公司雇用 UX 设计师类似，他们也应该雇用 DX 设计师来精心设计开发者在开发者门户上的体验。DX 策略师是管理开发者门户生命周期的核心角色。他们负责监督流程、标准和工具的变更，并确保这些内容扩展到各个解决方案团队。DX 策略师确保设计美学、结构和内容共同协作，为开发者创造愉快的体验。

策略师创建访问门户用户的角色，并设计用户旅程以满足他们的需求。例如，理想情况下，技术用户和非技术用户应有不同的入门用户旅程。

3.4 一致的UI/VI设计语言

优秀的设计不仅仅是美观，而是为了提升可用性，支持用户在平台上的探索、学习和交互。
设计应与品牌形象一致，文档应使用统一的风格和语气，保持所有解决方案的一致性。

3.5 提供高效的查找能力

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

开发者门户可能包含数十个页面，每个页面对应不同的解决方案。除了清晰的网站结构外，强大的搜索功能可以提高可发现性，让用户能够快速找到解决他们业务问题的解决方案。

应该有一个 API 探索器，用户可以在其中搜索和过滤提供的解决方案列表。在 API 参考文档中，拥有强大的搜索功能非常重要。API 参考页面的搜索栏应允许对 API 所有组件进行精细搜索。

查找能力取决于门户的结构和搜索/过滤功能。开发者门户应有明确的文档结构，让用户能够清楚地看到可用的解决方案范围，并且可以轻松根据类别过滤解决方案，排除不相关的内容。

在 API 参考页面内，用户应该能够根据资源、端点、参数和模式进行搜索和过滤。

3.6 兼顾所有能力阶层用户的入门流程

越来越多的 SaaS 公司也意识到，除了从头开发一个利用服务的应用程序外，还有其他方式可以使用技术产品。例如：平台可以提供用户通过最少代码即可轻松添加到网站的小组件。无代码或低代码解决方案打破了体验技术产品的门槛。

最好的开发者门户为每个技能水平的用户设计了入门流程。例如：技术用户可以从头开发一个应用程序，而非技术用户可以下载模板开始实验。

用户的入门流程通常是他们首次使用解决方案的体验。如果入门过程有阻碍，潜在客户可能会在完全试用 API 之前放弃。设置账户和获取凭证后，"快速入门" 部分会引导用户从头到尾体验与解决方案的交互，如 API。

在传达整体业务价值后，用户应立即被引导到各个解决方案页面，在这些页面上他们可以尝试使用 API、服务、客户端库或 SDK。这些页面的显著位置应提供一个指向入门流程的链接，帮助用户尽快体验产品。

在“快速入门”教程中，选择一个简单的用例，用户可以按照步骤从头到尾理解如何使用解决方案。

3.7 建立治理计划

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

建立治理计划需要跨部门的协作，制定标准，并获得各个业务单元的支持来完整实现计划。每个团队应负责遵守这些标准，并对其负责。治理计划应在业务材料到 API 参考的所有内容中统一语言、语气、风格和格式，并加强品牌建设。

3.8 正确记录 API 参考

API 参考文档是开发者快速理解 API 的简洁、详细的指南。高效的 API 参考页面允许开发者通过搜索和过滤快速找到资源、端点、字段或模式信息。

所有 API 组件是否都被准确记录？
每个资源是否都有文档说明？
各个端点和模式是否完整描述？
每个字段的描述是否说明了其目的、可选值的效果，以及与系统中其他字段的交互？
同一个字段的定义是否在规格中保持一致？

API 参考内容应遵循 API 风格指南，确定所有组件的标准。遵循风格指南确保 API 参考文档的内容一致且完整。没有准确且详细的参考信息，所有花哨的功能都是无用的。

通常，改进整体文档的第一步就是记录技术参考信息，因为在撰写教程之前，技术信息必须坚实可靠。

此外，设置"试一试"功能，为用户提供与 API 互动的实际操作体验。优秀的开发者门户会根据用户账户信息自动填充这些互动小部件。

3.9 建立活跃的社区

社区通常是解决问题的第一线支持。许多开发者门户都有社区页面。一些海外公司使用工具，如 Discord 频道或公共 Slack 频道（国内企业微信、钉钉、飞书等）或者网络论坛等等，来按不同类别主持讨论。

如果用户可以通过在消息板上发布问题找到答案，他们就无需联系支持团队。如果公司参与社区，它可以将问题记录为错误或文档改进的反馈。社区不仅仅是讨论论坛。它们还可以促成小型会议或大型会议，帮助推广平台。

建议从一开始，你就应该考虑如何围绕公司的解决方案培育并发展一个社区。这不仅是长期的支持策略，也是产品推广的一部分。更隐蔽的社区形式包括鼓励开发者订阅新闻通讯，保持沟通渠道的畅通。

保持良好的反馈，开发者门户上应有多种机会供用户提供反馈。例如，每个 API 参考部分都应提供评分机制，并附有自由格式的反馈选项。

社区也是反馈的重要来源。一个积极使用产品并在社区中发帖的社区，是一个无需主动征求就能得到反馈的渠道。

3.11 定期发布更新状态

定期发布平台演变的更新是可靠性和可信度的信号。发布说明、状态和变更日志等都是保持用户知晓最新变化的补充文档。

3.12 提供案例研究和参考资料

案例研究结合使用产品的客户的推荐意见非常具有说服力。案例研究可以展示常见的业务挑战以及如何通过平台解决这些问题。用户可能会在案例研究中找到与自身情况类似的问题，并能立即看到他们可以如何利用工具完成特定任务或解决其他客户遇到的问题。

四、最佳开发者门户实例

以下盘点一下市面上特定类别中表现优秀的开发者门户。希望能帮到大家。

最佳 API 开发者友好：APIPark （APIPark.COM）

APIPark是一款免费开源的企业级API开放平台，帮助用户5分钟快速搭建企业专属的API开放门户，性能强悍、简单轻便可扩展，适用于多种用例。APIPark 即将为用户提供 API 交易系统、以及 AI Agent 的集成功能（敬请期待），助力企业和独立开发者在AI时代更好地融入API经济，实现赋能与创新。

常用平台支持：支持快速导入Eolink-APIKit、Swagger、Postman等业内常用 API工具的数据,快速完成 API 上级和发布。
内置API测试：提供内置的API测试功能,便于API对接。
灵活的插件系统：提供开放的插件架构便于二次开发。
OpenAPI：提供丰富的OpenAPI,便于将APIPark集成到企业内部系统。
Al Agent支持：提供易于被AlAgent集成的中间件。

最佳API参考：Stripe

Stripe是一个支付处理平台，其API参考文档设计直观。API 参考文档必须允许开发者在大量技术细节中快速找到所需的信息。Stripe提供了一个单页网站，可以通过点击左侧导航链接、向下滚动页面或进行搜索，快速导航到不同部分。

• 可折叠内容：几乎所有内容都是可折叠的，包括字段描述、表格、架构等。可以专注于所需的信息，而不必面对多余的杂乱。
• 可切换编程语言：可以通过一个按钮全局更改代码示例的编程语言。此外，还可以轻松地通过点击复制按钮将代码示例复制到剪贴板。
• 广泛的链接：每当需要深入解释时，API参考文档会提供链接，指向概念文档，供获取背景信息和教程。
• 多点反馈：可以对每个部分提供反馈，包括在评分后写下自由文本。

最佳可查找性：Visa

Visa开发平台允许用户利用Visa网络的强大功能进行API开发。该平台的突出特点在于它可以轻松过滤可用的API和服务，以找到所需的功能。在他们的产品浏览器中，可以按多个类别过滤API列表。通过过滤，可以快速找到解决特定业务挑战的API。

在过滤后的列表中，每个API的“卡片”包含该服务的简短描述，以及指向概述或文档页面的链接。概述中包含一般业务信息，而文档中则包含API参考。可以根据是否需要入门或查看技术参考文档，快速找到所需的文档。此外，还可以在用例页面找到适合情况的用例，包括推荐和案例研究。

最佳编码教程：Fiserv

Fiserv的开发者门户在逐步示例实现其API方面表现出色。“食谱”是为不同用例提供的教程，其中包含各种语言的代码示例。每个食谱都会逐步引导完成特定任务的过程，每一步都有注释提供更多上下文信息。这些食谱在主文档中访问时表现尤为出色，主文档在需要逐步指南时链接到具体的食谱。这种将代码示例集成到文档中的方式使得Fiserv的平台非常以用例为导向。

五、写在最后

在AIGC技术快速发展的背景下，互联网公司正在加大对开发者门户的投资力度。企业逐渐认识到，开发者门户不仅是外部资源，更是推动技术采用和商业转型的关键驱动力。通过提供清晰的API文档、丰富的示例代码和互动式的社区支持，企业能够显著提升开发者的使用体验，加快产品集成与应用的速度。

随着API经济的蓬勃发展，中国企业应积极把握这一机遇，构建和优化开发者门户，以吸引和留住开发者。API的商业化不仅能够为企业创造直接收入，如按使用量收费或订阅模式，还能通过促进第三方开发者的创新，形成多元化的生态系统，增强市场竞争力。

在市场环境不佳的情况下，API商业化更是企业的第二增长点。通过灵活的商业模式，企业可以在竞争激烈的市场中寻找新的盈利机会，拓展市场覆盖率，吸引新客户，并提升客户黏性。因此，开发者门户不仅是技术交流的平台，更是实现商业价值的重要支点，为企业在不确定的市场环境中提供持续的增长动力。