为了我们不断努力推广 Swagger，Swagger 团队最近推出了 SwaggerHub，这是一种在线服务，它将核心 Swagger 工具（UI、编辑器、代码生成器、验证器）集成到一个协作平台中，旨在使 Swagger 及其工具的入门更加容易。在本文中，我将重点介绍 SwaggerHub 公开的相应 API，该 API 允许您在 SwaggerHub 注册表中搜索、检索、创建和更新 Swagger 定义。这使您可以
- 将 SwaggerHub 中的 Swagger 定义的搜索和检索集成到现有的 API 工具中
- 将 Swagger 定义直接保存到 SwaggerHub
SwaggerHub API 可在 https://app.swaggerhub.com/apis/swagger-hub/registry-api/ 上获得，其 Swagger 2.o 定义可在 https://swaggerhub.com/api/swagger-hub/registry-api 上获得。
SwaggerHub API 标识符
在我们深入了解 API 本身之前，让我们快速看一下 SwaggerHub 如何识别 API - 因为此“方案”在 API 和 SwaggerHub 本身中都被广泛使用。
SwaggerHub 中的每个 Swagger 定义都由以下值标识
- owner - 拥有 API 的帐户
- api - 所有者帐户下 API 的唯一标识符
- version - 唯一的版本标识符
在 API 和 SwaggerHub 应用程序中，这些都按上述顺序组合为路径段，这使您可以使用以下任一方式直接链接到 SwaggerHub 上的 API 及其 API
https://swaggerhub.com/api/{owner}/{api}/{version}
或
https://api.swaggerhub.com/apis/{owner}/{api}/{version}
对于 SwaggerHub API，这些端点是
如果省略末尾的版本，您将得到略有不同的结果
- Web 版本将显示 API 的默认版本（可在 API 设置中配置）
- API 版本将返回 API 所有版本的 apis.json 列表
apis.json
对 SwaggerHub API 的许多 GET 调用以 apis.json 格式返回 API 列表。例如，https://api.swaggerhub.com/apis/swagger-hub/registry-api 将返回 SwaggerHub API 的所有版本列表。您可以在 apisjson.org 网站上阅读有关 apis.json 格式的信息。上面列表中的每个项目都包含许多特定于 SwaggerHub 的自定义“X-??”属性
- X-Version：SwaggerHub 中相应 API 的版本
- X-Created：该版本在 SwaggerHub 中创建的时间
- X-Modified：该版本在 SwaggerHub 中最后修改的时间
- X-Published：此 API 版本是否已在 SwaggerHub 上“发布”（表示它处于最终状态）
对于此特定列表，您应该在结果中获得（在撰写本文时）3 个项目；版本 1.0.0、1.0.1 和 1.0.2 - 以及相应的元数据。
身份验证
SwaggerHub API 公开的大多数资源不需要身份验证令牌 - 目前唯一需要的是对 /apis/{owner}/{api} 的 POST，它创建/更新指定的版本（稍后详细介绍）。要进行此调用，您需要提供包含 API 密钥的“Authorization”HTTP 标头，该 API 密钥可以通过 SwaggerHub UI 获得，使用以下步骤
- 在右上角的菜单中选择设置
- 选择左侧的 API 密钥
- 单击创建 API 密钥
此密钥不仅允许您在您的帐户下发布新的/更新的 API，还将在搜索和 API 列表中添加一些额外功能
- 一个额外的 X-UserRole apis.json 属性，指示经过身份验证的用户对于特定 API 具有什么角色（所有者、编辑、查看）
- 可以指定 filter=user 作为 API 搜索调用的查询参数，这将仅返回经过身份验证的用户有权访问的 API，作为所有者或协作者（X-UserRole 属性将为“所有者”或“编辑”）
搜索 SwaggerHub 注册表
好的 - 让我们直奔主题 - SwaggerHub API 的基本资源位于 https://api.swaggerhub.com/apis。
此资源将返回 SwaggerHub 注册表中所有公共 API 的分页列表（在撰写本文时，所有 API 都是公共的 - 但这种情况肯定会在不久的将来发生变化）。如 Swagger 定义所示，有许多查询参数可用于筛选
- query：搜索所有 API 的所有者、名称、swagger.info.title 和 swagger.info.description
- tag：仅返回带有指定标签的 API
- state：仅返回具有指定状态的 API
- page 和 limit：分页
- sort 和 order：排序和排序 (!)
因此，例如，如果您想查找已发布的财务 API，您将调用
在撰写本文时，它返回一个 API - 太棒了！
如果您想将搜索范围缩小到仅限特定所有者的 API，请按照 swagger.json 中的描述将其添加到路径中
您可能会注意到，您从上面的 API 调用中得到的结果与您在 SwaggerHub UI 中看到的结果完全相同，这仅仅是因为 SwaggerHub 在幕后对所有 API 搜索/检索/更新功能使用相同的 API。
搜索结果中的 API 版本
如您所见，每个 {owner}/{api} 仅返回一个条目 - 您不会获得该 API 每个版本的条目。API 的默认版本在 X-Version apis.json 属性中返回，同时在 Swagger 属性中提供指向其 swagger.json 的链接。此外，还会添加 X-Versions 属性，其中包含该 API 所有版本的逗号分隔列表；已发布的版本以星号为前缀。
例如，fehguy 的家庭自动化项目在上面的列表中具有以下属性
这表明默认版本设置为 1.0.0，但还有其他可用版本（1.0.1 和 1.0.2）。它还表明唯一发布的版本是 1.0.1。
向路径添加 API ID 将显示该 API 的所有版本。例如，以下内容返回 SwaggerHub 注册表 API 的所有版本
https://api.swaggerhub.com/apis/swagger-hub/registry-api
检索 API 定义
如上所示，检索 API 定义非常简单。只需使用端点 https://api.swaggerhub.com/apis/{owner}/{api}/{version} 即可检索 JSON 或 YAML 格式的 Swagger 定义（默认值为 JSON - 将 Accept 标头设置为“application/yaml”以获取 YAML 版本）。如果您想直接定位特定格式，可以将 swagger.json 或 swagger.yaml 追加到端点。例如，SwaggerHub 定义的 JSON 版本可在 https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.0/swagger.json 上获得。
创建/更新 API 定义
按照上述说明设置好 API 密钥后，您就可以在 SwaggerHub 注册表中创建和更新 Swagger 定义了。只需将实际的 Swagger 2.0 定义发布到 https://api.swaggerhub.com/apis/{owner}/{api}。
以下规则适用
- 您只能在您的帐户下更新/创建 API - 即使用您的用户名作为所有者。
- 目前，该文件必须包含语法有效的 YAML 或 JSON 内容。
- API 的版本将从 Swagger 定义的版本属性中提取 - 如果它缺失或无效，则该定义将被拒绝。
- 如果已存在具有该版本的 API 版本，则会使用新的定义对其进行更新（除非该版本已发布 - 在这种情况下，更新将被拒绝）。
就是这样！
简单又直接，对吧？ 您可以直接在浏览器中像上面描述的那样使用 API（因为大多数调用都是 GET 调用），也可以在 SwaggerHub 中使用集成的 Swagger-UI，网址为 https://swaggerhub.com/api/swagger-hub/registry-api/1.0.0/ui（请注意末尾的 "ui" - 它会自动在界面中选择 Swagger-UI 选项卡）。
现在，用您的集成来打动我们吧 - 我们很乐意在 https://swagger.org.cn 上分享它们。如果您想查看实际的集成示例，请查看 Ready! API SwaggerHub 插件的源代码，网址为 https://github.com/SmartBear/readyapi-swaggerhub-plugin。
继续使用 Swagger 吧！