Swagger UI 2.1 卡住“获取资源列表”

Posted 2023-02-19

【中文标题】Swagger UI 2.1 卡住“获取资源列表”

【英文标题】：Swagger UI 2.1 Stuck "fetching resource list"

【发布时间】：2015-01-18 17:17:10

【问题描述】：

我最近创建了一个 RESTful API，但几个月后我将不记得如何使用它。我决定使用 Swagger 记录我的 API，但是我快疯了。

我使用http://editor.swagger.io/ 创建了 YAML 文件，然后将其转换为 Swagger 可以使用的 JSON 文件。当我将文件放入 Swagger UI 时，它只是卡在fetching resource list: localhost/swagger.json 并且控制台显示Uncaught TypeError: Cannot read property '$ref' of undefined 。

我使用的是 Swagger UI 的 2.1.0-alpha.5 版本。

这是我的规范文件：

招摇：'2.0' 信息： 标题：标题 描述： 废话，废话，废话，等等 版本：“1.0b” 主机：api.example.com 方案： - http 基本路径：/v1 产生： - 应用程序/json 路径： /match.json： 得到： #summary：匹配数据 描述：用于获取有关匹配的数据 参数： - 名称：身份证 在：查询 描述：来自游戏的比赛ID 要求：真 类型：整数 格式：int32 - 名称：钥匙 在：查询 描述：用于身份验证的 API 密钥。 要求：真 类型：字符串 回复： 200： 描述：返回匹配数据 架构： 类型：数组 项目： $ref: '#/definitions/MatchData' 默认： 描述：意外错误 架构： $ref: '#/定义/错误' 定义： 匹配数据： 特性： 信息： 类型：整数 格式：int64 描述：关于比赛的一般信息 时间： 类型：整数 格式：int64 描述：关于开始/结束时间的信息 统计： 类型：数组 格式：int64 描述：关于比赛的统计数据 错误： 必需的： - 错误ID - 信息 特性： 错误编号： 类型：字符串 描述：错误 ID。 信息： 类型：字符串 描述：有关错误的信息。

【问题讨论】：

您如何托管 swagger.json？你如何运行 swagger-ui？

@webron：“swagger.json”文件位于我的 htdocs 目录的根目录中。来自 repo 的“dist”目录也位于根目录，但已重命名。我正在使用 xampp 来托管它。

【参考方案1】：

我已经测试了您的规范，虽然我没有遇到与您相同的错误，但该规范确实无效。

如果您查看#/definitions/MatchData/properties/stats，您会看到您定义了type: array，但您没有在它旁边提供“items”属性来说明它是哪个数组（这是强制性的）。您可能打算像上面的属性一样使用type: integer，它与format: int64 一起使用。

由于我不知道您打算提供什么，因此很难给出准确的解决方案，但如果您添加您打算做什么的评论，我可以提供更详细的答案。

经过一些额外的测试，我发现 UI 中存在错误。在您进行修改并加载规范后，除非您单击 Expand Operations 链接，否则操作本身不会展开。我已经打开了一个 issue 关于它，请随时关注它。

【讨论】：

我最终只是重写了整个规范以备不时之需。我也有同样的错误，阻止我打开这些部分。感谢您的帮助。

【参考方案2】：

这个问题可能是由于 yaml 文件中的一些缩进错误实际上没有显示在 Swagger 编辑器中。检查您的所有定义以及它们是否在您可以在 Swagger 编辑器中看到的预览中按预期显示（尤其是检查 MatchData）。

你也可以尝试给予：

responses:
200:
  description: Returns match data
  schema:
    type: array
    items:
      schema:
        $ref: '#/definitions/MatchData'

【参考方案3】：

对于我们的案例，我们使用了 Swagger-php，我们有： * @SWG\响应（ * 响应=200， * 描述="应用响应" * @SWG\架构（ * 类型="数组" * ) * ),

但我们错过了“* @SWG\Items(ref="#/definitions/pet")”。删除“@SWG\Schema(”后，它可以工作，例如

 *     @SWG\Response(
 *         response=200,
 *         description="app response"
 *     ),