首页 博客 API 标准化...

API 标准化常见问题：关于使用 Swagger 工具大规模构建和执行 API 标准的热门问题

Ryan Pinkham
  2019 年 1 月 3 日

在 12 月，我们在 SwaggerHub 中发布了强大的新功能 API 标准化，使团队能够大规模构建和执行 API 样式指南。

在新年之前，我们举办了一次免费培训，使用 Swagger 大规模构建和执行 API 标准。在 60 分钟的会议中，我们对新功能进行了现场演示，并讨论了组织如何使用 Swagger 工具和 OpenAPI 规范来标准化其 API 设计。

超过 1000 人参加了会议，我们收到了大量关于团队如何使用 SwaggerHub 和 OAS 来实施这些策略的问题。但是，我们也收到很多因年底日程繁忙而无法参加网络研讨会的人的反馈。

我们很高兴地宣布，在 1 月 10 日，我们将 举办网络研讨会的特别重播！作为预览，我们也想分享并回答第一次会议中的热门问题。请查看以下内容，并务必预定您在 1 月 10 日上午 10 点和下午 2 点（美国东部时间）参加网络研讨会的位置。

SwaggerHub 中新的 API 标准化功能是否支持从我们的内部样式指南添加自定义规则的选项？

此功能在功能的初始版本中不受支持。如果您确实希望看到将规则添加到 API 标准化中，请在 Twitter 上与我们联系 @swaggerhub。我们需要您的反馈，以便我们能够继续改进工具以满足 API 团队的需求。

当我们在 SwaggerHub 中启用 API 标准化时，它是否适用于所有 API 和每个版本的 API？

API 标准化允许您在组织级别设置规则，并将这些规则应用于 SwaggerHub 中目录内的所有 API 定义。当您创建新版本的定义或更新现有版本时，该功能将自动验证并根据您帐户中定义的规则提供反馈。

API 标准化是否适用于最新版本的 OpenAPI 规范 OAS 3.0？

是的，API 标准化支持 OAS 3.0，但有一些规则例外。您可以在下面查看完整的规则和例外列表：

操作

  • 必须存在 OperationId 且为非空字符串

  • 必须存在操作摘要且为非空字符串

  • 摘要应以大写字母开头并以点结尾

  • 必须存在操作描述且为非空字符串

  • 操作必须具有标签且为非空字符串（仅限 OpenAPI 2.0）

  • 操作必须只有一个标签

  • 操作必须至少有一个 2xx 响应

  • 操作必须具有默认响应

API 信息

  • 必须存在 API 标题且为非空字符串

  • 必须存在 API 描述且为非空字符串

  • 必须存在 API 联系人且为非空字符串

  • 必须存在 API 许可证且为非空字符串

模型

  • 所有模型属性都必须有示例（仅限 OpenAPI 2.0）

  • API 不得有本地定义（即，只允许 $refs）（仅限 OpenAPI 2.0）

关于如何从代码生成定义，您有什么建议吗？我们在为现有 API 生成有用的接口时遇到问题？

有一些开源工具和库可以帮助从现有 API 生成 OpenAPI 定义。Swagger 团队支持一些用于从现有 API 生成 OAS 的库，其余的则由 OAS 社区维护：

您可以在此处浏览其他支持 OAS 的开源工具。

我们可以创建可在多个规范文件中使用和引用的通用模型吗？

SwaggerHub 通过域功能支持此功能。域是可以在 SwaggerHub 中存储并在 SwaggerHub 编辑器中从定义中引用的可重用组件。

域可以包含以下组件（它们的任意组合）：

  • 定义 – 描述 API 输入和输出的数据模型。

  • 路径项 – 可以在 API 之间重用的 API 路径（例如 GET、POST、PUT 操作）。

  • 参数 – API 调用的参数：路径参数、查询字符串参数、自定义标头、正文字段。

  • 响应 – API 调用返回的响应：HTTP 状态代码和响应数据模型。

了解更多

SwaggerHub 是否与我们的源代码控制存储库一起使用？

SwaggerHub 提供与 GitHub、Bitbucket 和 GitLab 的源代码控制集成。该集成允许您将 API 定义、自动生成的服务器代码或客户端 SDK 与现有存储库同步。每次您在 SwaggerHub 中保存 API 时都会完成同步。您可以完全控制将在目标存储库中添加、更新或忽略哪些文件。

与其将您的 OAS 定义托管在 GitHub 的各种存储库和分支中，您现在可以利用 SwaggerHub 作为您所有 API 设计和文档需求的单一来源，同时仍使它们与您在 GitHub 或任何其他源代码控制存储库中的源代码保持同步。

了解更多

我们应该使用哪些指标来衡量 API 质量？

在网络研讨会期间，我们预览了 2019 年 API 状态报告中的新数据，该报告将于 2019 年 1 月发布。当涉及到组织如何衡量质量时，前三个回应是：性能、可用性/开发者体验以及正常运行时间/可用性。我们还发现，用于交付高质量 API 的主要工具是：API 文档工具、API 功能测试工具、CI/CD 工具。

我们将在 1 月份分享报告中的更多见解，其中包括关于 API 生命周期中（从规划和设计到测试和监控）质量观点的详细解读。

Swagger 和 OpenAPI 之间有什么区别？

理解 Swagger 和 OpenAPI 规范之间关系的最简单方法是：

  • Swagger 是由 SmartBear 团队支持和开发的开源、免费和专业工具的集合，它们支持 OpenAPI 规范。

  • OpenAPI 是规范的名称，它受到 Swagger 工具和来自 Swagger 工具生态系统之外的不同供应商的数百种其他工具的支持。

在 2015 年该规范被捐赠给 Linux 基金会下的 OpenAPI 倡议后，该规范正式更名。

了解更多

我可以查看对现有 API 所做的更改吗？在接受这些更改之前，是否有流程来审查这些流程？

SwaggerHub 提供了托管和维护 API 定义多个版本的能力。这意味着您可以拥有一个已发布的版本，该版本已准备好进行开发，并在您的 API 发展时继续处理定义的下一个版本。

我们看到团队跟踪对 API 定义所做更改的一种方法是使用 SwaggerHub 编辑器中的注释功能。这使您可以直接在编辑器内添加反馈、请求更改和解决问题。

在审查和合并对 API 的更改时，团队可以利用 SwaggerHub 中的比较和合并功能。此功能使您可以将定义的工作版本中的更改与原始发布的版本进行比较。作为架构师或经理，您可以查看所做更改的可视化呈现，并且可以选择接受或拒绝更改。如果您有一组您知道要强制执行的跨定义的规则，并且不想手动审查和合并这些更新，则可以在组织设置中的 API 标准化面板中选择它们。

我们在 CI 管道中采用代码优先的方法。是否可以进行自动化测试，该测试从代码生成 swagger，将其提交到您的 API，并根据规则获得指示其是否有效的响应？

虽然我们看到许多团队和组织通过其 Web 界面使用 Swaggerhub，但平台底层的 API 同样强大。如果您是通过代码注释或框架动态生成 OpenAPI，则对 Registry API 进行简单的 POST 调用将允许验证该定义并将其存储为更大的内部目录的一部分。此工作流程不仅使提交新定义变得容易，而且还可以轻松地提取定义以进行测试或文档记录。如果您有兴趣更详细地了解我们的“代码优先”方法，我们最近的网络研讨会涵盖了一些可用的工作流程和插件。

了解更多

有兴趣了解新的 API 标准化功能是如何运作的吗？请加入我们在 1 月 10 日的特别网络研讨会重播。立即注册

您可能也喜欢