为了持续推广 Swagger，Swagger 团队最近推出了 SwaggerHub，这是一个在线服务，它将核心 Swagger 工具（UI、Editor、Codegen、Validator）集成到一个协作平台中，旨在让用户更轻松地开始使用 Swagger 及其工具。本文将重点介绍 SwaggerHub 提供的相应 API，该 API 允许您在 SwaggerHub 注册表中搜索、检索、创建和更新 Swagger 定义。这使您能够
- 将 SwaggerHub 中的 Swagger 定义搜索和检索功能集成到现有 API 工具中
- 直接将 Swagger 定义保存到 SwaggerHub
SwaggerHub API 可在 https://app.swaggerhub.com/apis/swagger-hub/registry-api/ 访问，其 Swagger 2.0 定义可在 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，这些端点是
如果您省略末尾的版本，您将获得略微不同的结果
- 网页版将显示 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: 相应 API 在 SwaggerHub 中的版本
- X-Created: 该版本在 SwaggerHub 中创建的时间
- X-Modified: 该版本在 SwaggerHub 中最后修改的时间
- X-Published: 如果此 API 版本已在 SwaggerHub 上“发布”（表示其处于最终确定状态）
对于此特定列表，您应该会得到（在撰写本文时）结果中的 3 个项目；版本 1.0.0、1.0.1 和 1.0.2——以及相应的元数据。
身份验证
SwaggerHub API 公开的大多数资源不需要身份验证令牌——目前唯一需要的是 POST 到 /apis/{owner}/{api} 的调用，它用于创建/更新指定版本（稍后将详细介绍）。要进行此调用，您需要提供一个“Authorization”HTTP 标头，其中包含可通过 SwaggerHub UI 获取的 API 密钥，具体步骤如下：
- 在右上角菜单中选择“设置”
- 选择左侧的“API 密钥”
- 点击“创建 API 密钥”
此密钥不仅允许您在您的账户下发布新的/更新的 API，它还将为搜索和 API 列表添加一些额外功能
- 一个额外的 X-UserRole apis.json 属性，指示已验证用户对于特定 API 拥有的角色（owner、edit、view）
- 可以在 API 搜索调用中将 filter=user 指定为查询参数，这将仅返回经过身份验证的用户作为所有者或协作者拥有访问权限的 API（X-UserRole 属性将是“owner”或“edit”）
搜索 SwaggerHub 注册表
好的，我们直接进入主题——SwaggerHub API 的基本资源位于 https://api.swaggerhub.com/apis。
此资源 将返回 SwaggerHub 注册表中所有公共 API 的分页列表（在撰写本文时，所有 API 都是公共的——但这种情况在不久的将来肯定会改变）。如 Swagger 定义所示，有许多查询参数可用于过滤：
- query: 搜索所有 API 的 owner、name、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 Registry API 的所有版本
https://api.swaggerhub.com/apis/swagger-hub/registry-api
检索 API 定义
检索 API 定义非常简单，如 上所示。只需使用端点 https://api.swaggerhub.com/apis/{owner}/{api}/{version} 即可检索 JSON 或 YAML 格式的 Swagger 定义（默认是 JSON——对于 YAML 版本，将 Accept Header 设置为“application/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 定义 POST 到 https://api.swaggerhub.com/apis/{owner}/{api}。
以下规则适用：
- 您只能在您的账户下更新/创建 API——即以您的用户名作为所有者。
- 目前，文件必须包含语法有效的 YAML 或 JSON 内容。
- API 的版本将从 Swagger 定义中的 version 属性中提取——如果它缺失或无效，则该定义 将被拒绝。
- 如果该版本已存在 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 持续前进！