API 开发人员对 API 设计和微服务的见解

在过去的一年中，我们看到，在投资微服务架构的软件团队中，SwaggerHub 平台的采用率出现了大幅增长。在三天的时间里，我们有机会与处于微服务和 API 采用历程不同阶段的人们进行了数百次对话。很高兴听到这么多人使用 Swagger 工具和 OpenAPI 规范来帮助实现他们的微服务架构，并了解更多关于我们如何继续发展 SwaggerHub 以帮助满足 API 团队的需求的信息。作为今年活动的后续，我们想分享一些从 DockerCon 2017 的对话中了解到的重要见解。

注：SwaggerHub 团队最近前往德克萨斯州奥斯汀参加2017年 DockerCon。DockerCon是世界上最大的容器技术会议，汇集了来自 Docker 社区的 5,000 多名开发人员、DevOps、系统管理员和其他人员。

OpenAPI 规范在微服务转型中扮演关键角色

从单片应用程序转向微服务架构的组织通常依靠 API 来公开服务，以便彼此通信。为了更好地通过 API 公开服务，需要为这些 API 提供一个通用接口，以准确说明每个服务应该做什么。OpenAPI （Swagger） 规范 （OAS）  已成为定义此合同的标准格式，它提供了一个通用接口，以人机可读的方式定义客户端和服务之间的 SLA。对于我们在 DockerCon 上一周采访过的团队来说，使用 OAS 定义 API 的主要用例是生成必要的文档，以便内部团队使用他们的 API，其中Swagger UI是该规范最受欢迎的实现。

多数团队依旧采用“代码优先”的 API 开发策略

关于采用设计优先方法开发 API或构建微服务的好处，已经有很多文章进行了阐述。设计优先方法首先涉及设计和定义微服务的接口，然后审查和稳定此合同，最后实现服务。 但是，尽管设计优先可能是理想的，但我们采访的大多数团队仍然遵循代码优先方法，他们使用某种开源工具组合从现有 API 生成 Swagger 文件 — 无论是在运行时还是在构建时。 对于我们采访的大多数人来说，决定采用“代码优先”方法来使用 Swagger 的原因是，与采用设计优先方法相比，它可以更快地实现。代码优先方法中的自动化要容易得多，这一事实有助于加强这种情况，许多库支持脚手架服务器代码、功能测试和部署自动化。   

风格一致性是API团队日益关注的问题

无论您的团队使用哪种架构来实现软件系统，如果您的团队非常重视良好的 API 开发人员体验，那么您可能会为您的团队制定一些指导方针。但是，当我们与个人讨论他们如何执行这些指导方针时，显然仍有改进的空间。 我们在讨论中听到的四个常见趋势是：

• 跟踪正在处理的所有 Swagger 文件
• 处理现有 API 的版本控制
• 在整个开发团队中强制执行样式指南
• 更轻松地在多个服务中重用通用设计对象

SwaggerHub 旨在解决这些挑战，它为您的整个团队提供了一个集中位置，让他们能够使用 Swagger 完成 API 的整个生命周期，同时使用域和样式验证器推动 API 设计的一致性和可重用性。 样式验证器可确保您的 RESTful 接口遵循基于组织要求的标准蓝图。这可能意味着确保所有接口都具有驼峰式运算符、在其响应数据包中定义的示例或其模型在本地定义。在域中，您可以存储通用的可重用语法（无论是模型还是请求-响应对象），这些语法可以在公开微服务业务功能的多个 API 中快速引用。

API管理在微服务架构中至关重要，急需优化设计

API 管理解决方案在微服务的编排中发挥着重要作用。凭借安全、监控、分析和发现机制，这些平台可帮助处理微服务架构中的大量 API。 但是，尽管许多 API 管理解决方案都提供设计功能，但对专用 API 设计工具集的需求也变得显而易见。良好的 API 设计对于任何面向公共或私有的 API 都很重要。

正如一位 Swagger 用户在我们展位的一次讨论中所说：“您需要为处理 API 的内部团队提供与外部开发人员相同的高质量体验。” 设置样式指南后，您需要一个能够为您的 API 设计提供一流处理的工具。对于刚开始使用 Swagger 的团队，像Swagger Editor这样的开源工具可以提供编写和更新定义所需的工具。对于需要将设计与 API 管理平台无缝集成的高级团队，像SwaggerHub这样的完全集成的平台可以提供帮助。

API团队寻求改进API文档的托管和管理方法

无论您是使用 API 公开服务，还是在自己的软件架构中使用，拥有最新且易于访问的文档都很重要。这是我们听到团队首先开始实施 Swagger 的最大原因。但是，当您的 API 文档从一个团队中的几个不同版本变为数十甚至数百个不同的 API 时，维护这些文档可能会成为一个问题。 我们从 Swagger 用户那里听到的一个常见解决方案是将文档托管在 GitHub 或 Bitbucket 等源代码控制主机上。但是，虽然这些工具非常适合托管源代码，但它们仍然无法让您轻松地从一个中心位置访问所有可用的不同文档。因此，大多数团队会改为寻找内部解决方案。 

我们努力在 SwaggerHub 中提供替代解决方案，让您可以从一个集中托管的平台托管和维护所有 API 文档。SwaggerHub 可以充当您组织的内部 API 目录，能够管理隐私、发布和取消发布版本，甚至使用我们的企业计划在您自己的服务器上托管。

原文链接：API Design and Microservices: Insights from Conversations with 500 API Developers