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. 此 API 定义的 YAML在结构上看起来与其他 API 定义的 YAML 相同
4. Swagger 验证器告诉我 YAML 是有效的：

我已经经历了很多不同的 StackOverflow 问答和 GitHub 问题，其中包含类似的错误消息，但它们大多与 YAML 无效或不受支持的同级相关$ref，但这里似乎并非如此。

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

我可以采取什么措施来避免收到这些消息？

---

如果有人想要 SSCCE：

• 下载分支
• 跑步mvn jetty:run-war
• 打开http://localhost:8085/api-explorer

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

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

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

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

或者使用此插件完全删除“Errors”块（即不将其添加到 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]自动生成的请求/响应示例中的值POST /search。

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