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

user_1654265 0
Viewed 6479

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:

enter image description here

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:

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

enter image description here

swagger-2.0 swagger-ui swagger rest yaml
1 Answers

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