使用原型作为 API 产品规范

作为 SendGrid 的开发人员体验产品经理，我的任务是识别涉及我们 API 的机会、功能和产品。 我一直在做的一件事是确定方法，以便更有效地将我的产品创意传达给其他 PM、工程师和客户。

我了解到，单一的产品需求文档 (PRD) 不太理想，包含与产品规范相同的信息的可测试接口将是一个强大的替代方案。 PRD 的问题在于它们通常非常大并且主要是文本。 失去自己的位置或错过真正重要的事情太容易了。

我们在 UX 方面的朋友已经使用Invision等工具解决了这个问题，它们提供了一个您可以触摸和使用的可点击界面，而不是简单描述界面的文档或线框。 由于 API 是一个接口，我们需要一个允许与规范进行实时交互的工具，而不是文档中的一堆描述性文本和 JSON。

定义要求

这个作为产品规范的可测试接口应该是什么样的？ 它将如何运作？ 它存在吗？

在阅读 Marty Cagan 的《灵感：如何打造客户喜爱的产品》的第 18 章“重塑产品规范”时，我意识到我想分享一个我一直在使用的工具，它可以满足 Cagan 对产品规范的要求，其中大部分他的产品规格愿望清单，以及我自己的原型作为规格要求的个人清单。

卡根的要求*：

• 规范必须描述完整的用户体验。
• 规范必须准确地代表软件的行为。
• 您必须能够以所有利益相关者都能得到他们需要的方式来传达产品。
• 规格会改变
• 规范需要有一个单一的主表示，以减少歧义和版本问题。

卡根的愿望清单*：

• 您将需要补充原型 [with]：
  • 商业逻辑
  • 发布要求
  • 平台交付要求
  • 用例
• 我真的很想能够注释原型

我对原型规范的要求：

• 原型应该是规范。
• 文档应该集成到原型中。
• 公司中需要它的每个人都应该可以访问原型和文档。
• 客户应该能够访问原型的功能部分以进行用户测试。
• 原型应该取代规范并尽可能接近预期功能，而无需连接成品。
• 对原型进行更改和记录应该很容易。
• 制作 A/B 变体应该很容易，任何可以访问原型的人都可以对其进行测试。
• 从原型中导出客户文档应该很容易。

介绍停车灯

我一直在使用的几乎可以满足上述所有要求的工具称为Stoplight.io 。 它的核心是 API 文档引擎和 Web 代理。 它允许您使用直观的 UI 定义您的 API，该 UI 在幕后将 Swagger 和 RAML 的精华作为其规范引擎，并能够从任一格式导入或导出。

由于 StopLight 是一个文档工具，您可以为您的端点定义请求、响应、标头和描述。 使用代理功能，您可以调用您的 API 并验证您的调用是否符合您的规范或自动发现您的端点以自动编写大部分文档。

StopLight 的代理还有其他几个绝对令人惊叹的功能：

• 如果您的产品未完成或您不想代理您的请求，则能够对您的端点进行模拟调用。
• 用于在您的机器上测试原型的本地服务器。
• 用于在 Internet 上测试您的原型的远程服务器。
• 中间件，用 Javascript 编写，用于定义可以在调用原型端点之前和/或之后运行的代码。

如果您将我的愿望清单、Cagan 的规范要求和他的愿望清单与 StopLight 提供的功能进行比较，您会发现 StopLight 满足了所有需求和愿望：

• 原型及其功能的内部文档。
• 一个易于访问的完整功能原型。
• 一个可测试的界面，能够为用户测试和反馈切换可变功能。
• 一种针对特定对话对原型进行版本控制的简单方法，以便您可以近乎实时地修改原型的功能，以说明和验证您收到的反馈。

StopLight 中的工作流程很简单，任何人都可以完成，无论他们的技术能力如何：

• 创建一个新项目。
• 通过单击并键入有关端点、其参数、请求和响应的信息来添加规范。
• 在定义屏幕中添加有关您的原型的规范信息。
• 如果您有可选功能，请使用中间件添加它们。
• 开启嘲讽。
• 复制/粘贴模拟服务器的公共 URL 并分享它以获取反馈。

如果您正在拜访客户并想实时试验原型，只需将定义下载到您的计算机，创建一个以您的拜访命名的新项目，然后导入定义。 现在您可以在不更改原始原型的情况下更改任何您想要的东西。 当您返回并合并想法时，进行更改就像最初构建原型一样容易。

作为开发人员体验产品经理，StopLight 不仅帮助我更有效地完成工作，而且使用起来非常简单，并且由于文档在客户验证步骤之前开始并更新，因此使记录 API 的交付准备步骤变得容易在整个过程中。 StopLight 提供了许多其他用例和功能，但这可能是对我的工作影响最大的一个。

*Cagan 的要求和愿望清单直接引用自Inspired: How to Build Products Customers Love。