Swagger 中的奇怪 "Could not resolve reference: undefined Not Found" 消息 UI 3

Question

在将 Alfresco 的 REST API Explorer 从 Swagger UI 2 迁移到 Swagger UI 3 (3.38.0) 时，单个 API 定义引发了两个 无法解析参考：undefined Not Found 错误位于：

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

所有 API 定义在 Swagger 中工作正常 UI 2
所有 API 定义，但这在 Swagger 中工作正常 UI 3
this API definition seems structurally identical to the YAML of the other API definitions
Swagger 验证器告诉我 YAML 有效：

我经历了很多不同的 Whosebug Q&A 和 GitHub 具有类似错误消息的问题，但它们大多与 YAML 无效或 $ref 的不受支持的兄弟姐妹有关，但它不这里好像是这样。

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

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

如果有人想要 SSCCE：

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

然后 select Search API 定义并单击带有 /search API:

的绿色行

Answer 1

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

在您的示例 (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 架构 and/or SearchRequest.pivots 属性到 fix/work-around "pivots": [null] POST /search.

中自动生成的 request/response 个示例中的值

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

Swagger 中的奇怪 "Could not resolve reference: undefined Not Found" 消息 UI 3

Weird "Could not resolve reference: undefined Not Found" messages in Swagger UI 3

rest

yaml

swagger

swagger-ui

swagger-2.0