API 标准化常见问题解答：关于使用 Swagger 工具大规模构建和实施 API 标准的常见问题 

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

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

超过 1,000 人参加了会议，我们收到了大量关于团队如何使用 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 社区维护： 

• Java/Scala – Swagger-Core   

• C# – NSwag // Swashbuckle  

• Node.JS  – Swagger-express // HAPI-Swagger  

• Ruby  – Source2Swagger // OpenAPI-Rails  

• PHP – Swagger-PHP   

• Go – go-swagger   

• Python - Django-REST-Swagger // Flask-RESTplus  

• Spring - SpringFox  

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

我们是否可以创建可跨多个规范文件使用和引用的通用模型？ 

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

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

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

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

• 参数 – API 调用的参数：路径参数、查询字符串参数、自定义头、请求体字段。 

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

了解更多 

SwaggerHub 是否与我们的源代码管理仓库配合使用？  

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

您现在可以将 SwaggerHub 作为所有 API 设计和文档需求的真实来源，而不是将 OAS 定义托管在 GitHub 的各种仓库和分支中，同时仍能使其与 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 中的“比较与合并”（Compare & Merge）功能。此功能允许您将定义的工作版本中的更改与原始已发布版本进行比较。作为架构师或管理者，您可以直观地查看所做的更改，并选择接受或拒绝这些更改。如果您有一套您希望在所有定义中强制执行的规则，并且不想手动审查和合并这些更新，您可以在组织设置的 API 标准化面板中选择这些规则。  

我们采用代码优先的方法在 CI 流水线中工作。是否可以进行自动化测试，从代码生成 Swagger，将其提交到您的 API 并获得响应，指示它是否符合规则？ 

虽然我们看到许多团队和组织通过 SwaggerHub 的 Web 界面使用它，但平台底层的 API 同样强大。如果您通过代码注解或框架动态生成 OpenAPI，只需向Registry API 发送一个简单的 POST 调用，即可验证并将定义存储为更大的内部目录的一部分。这种工作流程不仅使提交新定义变得容易，而且拉取定义进行测试或文档化也变得直接。如果您有兴趣更详细地探索我们的“代码优先”方法，我们最近的网络研讨会涵盖了一些可用的工作流程和插件。 

了解更多 

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