与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设计。借助适合的工具，他们能够将设计作为一个继续演进的过程，而不是仅仅是开发之前的一个步骤。

采纳“设计优先”办法对企业来说既有短期商业价值，也有长期商业价值。团队可能依据正确的设计来生产正确的软件。团队在工作时可能充满信心，晓得本人走在正确的路线上。企业升高了公布谬误软件的危险，并带来了更统一的用户体验。

“设计优先”办法有助于将设计和开发阶段交融在一起，使这两个阶段相互影响。采纳这种办法的企业能够更快适应一直变动的需要，这种对变动的适应能力会转化为企业的竞争劣势。

“代码优先（Code First）”办法的挑战

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

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

  • 丧气的用户——如果API文档没有公布、不残缺或与理论部署的API不统一，API用户可能会感到丧气并抉择其余解决方案。
  • 谬误的API——如果团队没有自动化工具来领导设计，团队可能会构建和部署谬误的API。
  • 错失良机——如果团队没有公布其OpenAPI文档的过程，那么其余团队将无奈看到，这可能会导致反复工作并错失良机。
  • 不统一的开发人员体验——如果团队不应用工具来领导其应用的规范，他们可能会产生与其余团队不同的API实际与体验。

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

“代码优先”的团队如何转为“设计优先”？

“代码优先”团队能够采取一些理论的办法来改良他们的工作形式，向“设计优先”形式迈进。

  • 可信数据起源——团队能够找到将生成的文档用于更多的用处。他们能够将API定义视为在其DevOps流程中进行测试和部署的可信数据起源。
  • API发现——团队能够将文档公布到一个地方地位，供其余团队发现和试用。这有助于他们分享常识，并帮忙其他人找到他们的API。
  • 已公布和以后的文档解决——团队能够确保自动化公布文档的过程，以便文档始终保持最新。
  • 邀请适合的人员——团队能够让更多的开发人员参加API设计探讨，包含产品经理、QA工程师和DevOps工程师等。

“代码优先”团队能够通过认真改良开发人员体验，并减少团队之间的沟通来升高一些危险。他们也能够应用这些步骤逐步向“设计优先”过渡。

SwaggerHub如何提供帮忙？

无论采纳何种办法，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

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

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