如何使用OpenAPI扩展您的API设计流程

  2018年1月18日

尽管越来越多的组织将设计作为软件开发生命周期及其API生命周期中的关键一步,但很少有组织能够有效地大规模设计API。

当您在一个团队中处理数量有限的服务时,设计更容易管理,并且依靠PDF样式指南或维基页面可能足以使每个人保持一致。但是,当设计过程需要扩展到多个团队以及数百甚至数千个不同的API时,会发生什么呢?

创建一个真正可扩展的设计流程

我们推出了SwaggerHub,旨在改变团队协作设计和文档化API的方式。在过去的一年中,我们与数百名SwaggerHub用户进行了交流,以更好地了解他们如何将设计流程扩展到多个团队和不断增长的API数量。

CrowdFlower工程副总裁Cameron Befus分享了他从开源Swagger设计工具转向SwaggerHub以实现更具可扩展性的API设计的经验

CrowdFlower使用Swagger定义我们的API已有一段时间,而得益于SwaggerHub,这一过程变得明显容易。拥有像Swagger和SwaggerHub这样优秀的工具,它们在设计新服务时促进协作——并使这些服务的文档化和集成测试变得更加容易——这对我们的团队来说是一个巨大的帮助。

Bonotel的首席信息官Scot Hastings也分享了他为最近的API项目启动新设计流程的经验

“随着项目进一步推进,我们意识到需要加快流程并提高效率。我们希望自动生成用户界面,并促进内部和外部团队之间的协作,而不会出现麻烦或沟通问题……通过使我们能够更快地设计和开发RESTful API,我们可以更快地推出新服务和更新服务,”霍布斯说。“这使得SwaggerHub成为我们软件开发生命周期中的关键一环。”

像CrowdFlower和Bonotel这样的组织已经通过将OpenAPI(Swagger)标准化用于API设计,并采用无缝融入其API工作流程的工具,从而有效地扩展了API设计,并使他们能够在SwaggerHub中更有效地协作进行API设计。

它们也代表了我们从成功扩展其API设计流程的团队中看到的一些关键原则。

准备好扩展您的设计流程了吗?以下是您需要采取的几个重要步骤

1. 统一您的团队

良好的API设计依赖于API开发生命周期中所有利益相关者之间的有效协调。如果您的团队在设计要求上不一致,或者如果合适的人员无法获得对设计变更的必要可见性,那么当您尝试将规模扩展到少量API之外时,将会遇到摩擦。

组织尝试使团队成员在设计流程上保持一致的一种常见方式是通过Confluence或GitHub等协作工具。但尽管这些工具在软件开发生命周期中扮演着关键角色,但针对管理API设计工作流程的特定用例进行配置可能会很复杂。

SwaggerHub旨在帮助团队在其API的整个生命周期中保持一致。在SwaggerHub中,您可以创建组织并邀请团队成员协作进行API的设计和文档化。组织所有者可以根据团队成员在设计过程中的参与程度,为他们分配角色并管理访问权限。

了解更多关于在SwaggerHub中协作的信息。 

2. 提高设计流程的可见性

与团队在尝试扩展其API设计流程时可能面临的一致性挑战类似,还有一个艰巨的任务是提高团队的可见性。我们经常看到团队会从开源Swagger工具(如Swagger Editor和Swagger UI)开始他们的API设计之旅。虽然这些工具提供了有效建模和可视化API所需的功能,但它们并非旨在满足大型API团队的协作需求。

如果您正在使用OpenAPI来处理API设计,您会希望提供一个中心位置,让您的整个团队能够访问为设计不同服务所做的工作。您还需要确保当发生更改时,相关人员能够收到通知,并且您不会将可见性局限于分散的电子邮件、Slack消息和GitHub工单。

3. 减少依赖

API开发不仅是一个复杂的过程,对于涉及的团队来说,也可能是一个缓慢的过程。跨团队的依赖关系是阻碍团队从设计阶段转向生成代码、起草文档和编写测试用例的最大因素之一。团队减少依赖、从而实现更快开发的一种方法是通过API“模拟”或虚拟化。

SwaggerHub中的API自动模拟集成使用您规范中定义的静态响应来创建和维护API的模拟。您可以在SwaggerHub中创建新API时自动创建模拟,也可以在以后随时手动创建。模拟有助于您在设计API时对其进行测试,即在开发人员实现之前。此外,此集成允许客户端应用程序开发人员甚至在后端准备好之前就开始他们的工作。

无需编写任何代码,您就可以让API消费者针对模拟开发客户端,该模拟保证能以兼容且真实的有效负载进行响应。更重要的是,您可以通过在模型定义中使用“示例”结构,直接在OAS定义中调整有效负载。

4. 设置并执行设计要求

公司对API的投资是一项长期努力。设计标准不仅改进了API的实现,还决定了API如何更新或新API如何开发。一旦设计指南确定,就更容易在此基础上构建,并允许团队开发API,从而使组织能够扩展其设计和开发流程。

由于设计定义了客户端和服务如何交互,设计上的差异会导致服务开发阶段的混乱和额外开销。这些不一致之处只会倍增,其影响将在API生命周期中放大。例如,一个资源命名不一致的API在实现过程中可能在控制器中采用不同的命名风格。

SwaggerHub解决设计一致性问题的一种方法是使用我们内置的样式验证器,以检查您的API定义是否符合特定的描述标准。例如,您公司的指南可能要求所有属性都指定示例。样式验证器可帮助您自动化此类检查。在创建样式验证器集成时,您需要指定要执行的检查。

5. 提高设计的可重用性

我们经常从使用Swagger工具和OAS定义API的团队那里听到的一件事是,当在数百个API中定义多个端点时,设计过程可能会非常繁琐。当端点共享通用语法并具有相似的定义、路径项、参数和响应时,尤其如此。重复地单独定义每个端点可能会减慢设计过程,并导致API设计中的不一致。

这就是为什么SwaggerHub在设计过程中引入了域(Domains)的概念。域是可在多个API和其他域之间共享的可重用组件。一个域可以包含以下组件:定义、路径项、参数、响应。用户可以创建和版本化域,然后定义可存储在其中的可重用组件。这些组件可以由用户或API上的协作者从其他API或域中引用。

6. 集成您信赖的工具

能够快速地从设计阶段过渡到API的文档化、构建和部署,对于建立可扩展的API设计流程至关重要。即使是最好的设计标准,如果从API生命周期的初始阶段开始推进时遇到阻力,也无法帮助您扩展API设计。

API供应商解决此问题的一种方法是在更侧重于API管理的工具之上构建额外的设计功能。虽然拥有一个一体化解决方案很好,但这也会导致组织被锁定在单一解决方案中,当您想要引入新工具时,灵活性会大大降低。

在SwaggerHub中,我们采取了不同的方法——构建一个世界级的API设计平台,供团队用作其API设计过程的“单一事实来源”,然后提供与您的团队信赖的工具的无缝集成,以交付出色的API,包括:Apigee、AWS、Microsoft Azure或IBM API Connect等API网关;Bitbucket、GitHub和GitLab等源代码控制平台;以及用于功能测试的SoapUI等测试工具。

了解更多关于SwaggerHub API生命周期集成的信息。 

扩展您的设计流程

无论您已有现成的设计流程,还是刚刚开始采用“设计优先”的API开发方法,SwaggerHub都能帮助您的团队标准化API设计、实现跨团队协作,并通过OpenAPI/Swagger集中管理API设计工作流程。

免费试用SwaggerHub!了解为什么超过70,000名API开发人员、设计师、架构师、首席信息官(CIO)等信任SwaggerHub,并借助它扩展他们的API设计流程。

立即免费试用SwaggerHub.

有疑问或想了解更多关于如何改进API设计流程的信息?请联系SwaggerHub团队:[受电子邮件保护]

© . All rights reserved.