问题
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
- All the API definitions were working fine in Swagger UI 2
- All the API definitions but this work fine in Swagger UI 3
- The YAML of this API definition seems structurally identical to the YAML of the other API definitions
- 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