与SmartBear合作的很多公司都处于API旅程中的不同阶段。其中有些刚刚意识到他们需要一个API策略，而另一些则有整个团队去定义和实施一个API策略。但无论他们身处哪个阶段，他们都在寻找并想采用一种叫“API设计优先（API Design First）”的方法。

乍一看，您可能会觉得如果团队没有使用“设计优先”方法，那么他们可能会推迟设计，或者完全跳过设计阶段。但这并不是“设计优先”的真正意思。

相反的是，“设计优先”是指人们以一种人类和计算机都能理解的方式书写他们的API设计。其他方法也可能鼓励在软件开发过程中提前进行设计，但这些设计可能无法在后续的自动化或开发者工具中使用。

“设计优先”意味着团队中的每个人都使用相同的术语和概念，确保各种开发工具都可以使用相同的设计规范。采用这种方法的公司和团队可以减少设计和开发之间的鸿沟，这种API设计风格有许多优点，包括：

基于产品的API——团队可以在API设计过程的早期让产品经理和质量保证工程师加入进来，帮助塑造API的功能，从而使API的设计更加注重产品的需求和目标。

基于设计的开发——API开发人员可以利用API设计来推动开发工作。自动化工具可以指导他们应该构建什么，并确保他们根据设计构建API。

并行工作——在API本身完成之前，就可以开始构建API客户端。这让API使用者、API生产者和技术编写者能够并行工作，不必相互等待。

更短的反馈循环——API团队可以通过使用自动化工具来获取更快的反馈，验证他们的设计。团队可以在编写过程中设计并查看文档，不用等待开发人员交付可工作的代码。

帮助DevOps——DevOps团队可以在API部署到生产环境之前，使用API设计来测试API。他们可以使用自动化工具来检查实现的API是否符合设计规范，不用手动检查。

适应后期更改——团队可以在整个开发阶段持续地影响API设计。借助合适的工具，他们可以将设计作为一个持续演进的过程，而不是仅仅是开发之前的一个步骤。

采用“设计优先”方法对企业来说既有短期商业价值，也有长期商业价值。团队能够根据正确的设计来生产正确的软件。团队在工作时能够充满信心，知道自己走在正确的道路上。企业降低了发布错误软件的风险，并带来了更一致的用户体验。

“设计优先”方法有助于将设计和开发阶段融合在一起，使这两个阶段相互影响。采用这种方法的企业可以更快适应不断变化的需求，这种对变化的适应能力会转化为企业的竞争优势。

通常情况下，“代码优先”方法指的是团队从代码中生成机器可读的API定义，而不是自己去编写。他们将生成的文档作为构建资产而不是设计资产使用。“代码优先”方法并不代表团队忽略了设计，而是将设计隐藏在Jira工单、Confluence页面或文本文档中，而这可能会造成遗漏。

使用“代码优先”方法的团队错过了在整个开发过程中利用API设计的好处，而不仅仅是在编写代码时，而这也导致了一些潜在问题：

沮丧的用户——如果API文档没有发布、不完整或与实际部署的API不一致，API用户可能会感到沮丧并选择其他解决方案。

错误的API——如果团队没有自动化工具来指导设计，团队可能会构建和部署错误的API。

错失良机——如果团队没有发布其OpenAPI文档的过程，那么其他团队将无法看到，这可能会导致重复工作并错失良机。

不一致的开发人员体验——如果团队不使用工具来指导其使用的标准，他们可能会产生与其他团队不同的API实践与体验。

但说实话，任何团队要转向“设计优先”方法都需要付出一定的努力。尤其是对于大型企业来说，它们需要有专门负责引导过渡的人员。不过，无论公司的规模如何，都需要有明确的转向意愿和意识，因为从传统的代码优先转向设计优先是不会自动发生的。

“代码优先”团队可以采取一些实际的方法来改进他们的工作方式，向“设计优先”方式迈进。

可信数据来源——团队可以找到将生成的文档用于更多的用途。他们可以将API定义视为在其DevOps流程中进行测试和部署的可信数据来源。

API发现——团队可以将文档发布到一个中央位置，供其他团队发现和试用。这有助于他们分享知识，并帮助其他人找到他们的API。

已发布和当前的文档处理——团队可以确保自动化发布文档的过程，以便文档始终保持最新。

邀请合适的人员——团队可以让更多的开发人员参与API设计讨论，包括产品经理、QA工程师和DevOps工程师等。

“代码优先”团队可以通过认真改进开发人员体验，并增加团队之间的沟通来降低一些风险。他们也可以使用这些步骤逐渐向“设计优先”过渡。

无论采用何种方法，SwaggerHub都可以融入您的开发工作流程。SmartBear认为重要的是让产品在用户的API开发过程中提供支持，所以提供了很多工具，帮助团队实现这一目标。

设计工具——您可以尝试使用SwaggerHub编辑器来编写OpenAPI文档、用标准化的工具编写一致的API，以及使用协作工具来讨论API的设计。

快速反馈工具——您可以尝试API自动模拟以获得快速反馈，并在开发人员构建之前尝试设计。

集成工具——您可以尝试使用源代码管理集成将API设计导入开发工作流，也可以尝试使用API管理工具来自动执行API部署。

DevOps和自动化——您可以尝试使用SwaggerHub API注册表，将SwaggerHub集成到DevOps流程中，并构建将SwaggerHub视为事实来源的自动化工作流程。

开发者工具——您可以尝试使用SmartBear的Codegen来生成客户端SDK，以便在软件项目中轻松使用API。它还可以生成服务器存根，用于启动API提供商的开发过程。

开源工具——您可以联系SmartBear授权合作伙伴——龙智，试用业界最佳的OpenAPI开源工具，如Swagger编辑器和Swagger UI。

SwaggerHub为团队提供了构建出色API所需的工具，无论他们使用的是“代码优先”方法还是“设计优先”方法。

SwaggerHub是一个优秀的API设计和协作平台，致力于使API设计成为开发过程中的可信数据来源。SmartBear为企业提供实施API策略所需的工具，并为处于API旅程任何阶段的人们提供帮助。

文章来源：https://smartbear.com/blog/embracing-an-api-design-first-approach/