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

こ雲淡風輕ζ 提交于 2021-01-28 11:54:53

问题


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:


回答1:


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: []


来源:https://stackoverflow.com/questions/65584131/weird-could-not-resolve-reference-undefined-not-found-messages-in-swagger-ui

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!