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

Question

迁移 Alfresco 的 REST API Explorer 时从 Swagger UI 2 到 Swagger UI 3 (3.38.0)，单个 API 定义引发了两个 Could not resolve reference: 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

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 Issues，但它们大多与 YAML 无效或 $ref 不受支持的 sibling 有关，但事实并非如此这里似乎就是这种情况。

这是 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

与此同时，您可以隐藏红色“错误” block - 通过将一段 CSS 添加到您的 index.html

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

或使用 this plugin完全删除“错误” block (即不将其添加到 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: []