奇怪的“无法解析引用:未定义未找到"Swagger UI 3 中的消息 [英] Weird "Could not resolve reference: undefined Not Found" messages in Swagger UI 3

问题描述

将 Alfresco 的

我经历了很多不同的 StackOverflow Q&A 和 GitHub 问题，并带有类似的错误消息，但它们主要与 YAML 无效或 $ref 的不支持的兄弟相关，并且它没有似乎不是这里的情况.

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

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

---

如果有人想要 SSCCE:

• 下载

  解决方案

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

  在你的例子中(alfresco-search.yaml)，错误是由 RequestPivot 架构中的递归触发的:

   RequestPivot:描述:枢轴列表.类型:对象特性:钥匙:描述:对应于匹配字段方面标签或统计信息的键.类型:字符串支点:类型:数组项目:$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 {显示:无！重要；}

  或使用这个插件删除错误"完全阻止(即不将其添加到 DOM).插件代码需要在SwaggerUIBundle构造函数之前添加，然后插件名称需要包含在构造函数中的plugins列表中.

  //index.html<脚本>window.onload = 函数(){//隐藏整个错误容器const HideAllErrorsPlugin = () =>{返回 {包裹组件:{错误:() =>() =>空值}}}const ui = SwaggerUIBundle({网址:...，...插件: [HideAllErrorsPlugin,//<--------------SwaggerUIBundle.plugins.DownloadUrl],...})}

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

   RequestPivot:描述:枢轴列表.类型:对象...示例:# <--- 自定义示例钥匙:我的钥匙支点:- 键:另一个键支点:[]

  While migrating Alfresco's REST API Explorer from Swagger UI 2 to Swagger UI 3 (3.38.0), a single API definition raised two Could not resolve reference: undefined Not Found errors at :

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

  and

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

  1. All the API definitions were working fine in Swagger UI 2
  2. All the API definitions but this work fine in Swagger UI 3
  3. The YAML of this API definition seems structurally identical to the YAML of the other API definitions
  4. The Swagger Validator tells me that the YAML is valid:

  I've gone through a lot of different StackOverflow Q&A and GitHub Issues with similar error messages, but they were mostly related to YAML invalid or with unsupported siblings of $ref, and it doesn't seem to be the case here.

  Is this a false positive from Swagger UI 3, or is there something wrong with the API definition itself?

  Is there something I can do to avoid getting these messages?

  
  
  

  ---

  In case someone wants an SSCCE:

  • download the branch
  • run mvn jetty:run-war
  • open http://localhost:8085/api-explorer

  Then select the Search API definition and click on the green row with the /search API:

  解决方案

  Your API definition is fine. This error is a bug/limitation of Swagger UI's $ref resolver - sometimes it fails on long $ref + allOf/oneOf/anyOf chains, recursive schemas, circular references, or a combination thereof.

  In your example (alfresco-search.yaml), the error is triggered by the recursion in the RequestPivot schema:

    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'
  

  Here are related issues in Swagger repos that you can track:
  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

  
  

  In the meantime, you can hide that red "Errors" block - either by adding a piece of CSS to your index.html

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

  or by using this plugin to remove the "Errors" block entirely (i.e. not add it to the DOM). The plugin code needs be added before the SwaggerUIBundle constructor, and then the plugin name needs to be included in the plugins list in the constructor.

  // 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
      ],
      ...
    })
  
  }
  

  I also recommend adding a custom example to the RequestPivot schema and/or the SearchRequest.pivots property to fix/work-around the "pivots": [null] value in auto-generated request/response examples in POST /search.

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

  这篇关于奇怪的“无法解析引用:未定义未找到"Swagger UI 3 中的消息的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！