Swagger UI 3 中奇怪的“无法解析参考：未定义未找到”消息

Question

在将 Alfresco 的 REST API Explorer 从 Swagger UI 2 迁移到 Swagger UI 3 (3.38.0) 时，单个 API 定义引发了两个无法解析引用：未找到未定义 错误：

paths./search.post.parameters.0.schema.properties.pivots.items.properties.pivots.items.$ref

和

paths./search.post.responses.200.schema.properties.list.properties.context.properties.request.properties.pivots.items.properties.pivots.items.$ref

1. 所有 API 定义在 Swagger UI 2 中都可以正常工作
2. 所有 API 定义，但在 Swagger UI 3 中都可以正常工作
3. this API definition 的 YAML 在结构上似乎与 the other API definitions 的 YAML 相同
4. Swagger 验证器告诉我 YAML 有效：

我经历了很多不同的 StackOverflow Q&A 和 GitHub 问题，并带有类似的错误消息，但它们大多与 YAML 无效或 $ref 的兄弟姐妹不受支持有关，而这里似乎并非如此.

这是 Swagger UI 3 的误报，还是 API 定义本身有问题？

我可以做些什么来避免收到这些消息吗？

---

如果有人想要 SSCCE：

• 下载the branch
• 运行mvn jetty:run-war
• 打开http://localhost:8085/api-explorer

然后选择Search API 定义并单击带有/search API 的绿色行：

Answer 1

您的 API 定义很好。此错误是 Swagger UI 的 $ref 解析器的错误/限制 - 有时它会在长 $ref + allOf/oneOf/anyOf 链、递归模式、循环引用或它们的组合上失败。

在您的示例 (alfresco-search.yaml) 中，错误是由 RequestPivot 架构中的递归触发的：

  RequestPivot:
    description: A list of pivots.
    type: object
    properties:
      key:
        description: A key corresponding to a matching field facet label or stats.
        type: string
      pivots:
        type: array
        items:
          $ref: '#/definitions/RequestPivot'

您可以跟踪 Swagger 存储库中的相关问题：
https://github.com/swagger-api/swagger-js/issues/1570
https://github.com/swagger-api/swagger-ui/issues/5726
https://github.com/swagger-api/swagger-ui/issues/5820

与此同时，您可以隐藏红色的“错误”块 - 或者通过在您的 index.html 中添加一段 CSS 代码

.errors-wrapper {
    display: none !important;
}

或使用this plugin 完全删除“错误”块（即不将其添加到 DOM）。插件代码需要在SwaggerUIBundle构造函数之前添加，然后插件名称需要包含在构造函数的plugins列表中。

// index.html

<script>
window.onload = function() {

  // hide the entire Errors container
  const HideAllErrorsPlugin = () => {
    return {
      wrapComponents: {
        errors: () => () => null
      }
    }
  }

  const ui = SwaggerUIBundle({
    urls: ...,
    ...
    plugins: [
      HideAllErrorsPlugin,                // <---------------
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    ...
  })

}

我还建议将自定义 example 添加到 RequestPivot 架构和/或 SearchRequest.pivots 属性以修复/解决 @ 中自动生成的请求/响应示例中的 "pivots": [null] 值987654342@.

  RequestPivot:
    description: A list of pivots.
    type: object
    ...
    example:     # <--- Custom example
      key: MyKey
      pivots:
        - key: AnotherKey
          pivots: []