迁移 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
- 所有 API 定义在 Swagger UI 2 中都运行良好
- 除此之外的所有 API 定义在 Swagger UI 3 中都可以正常工作
- this API definition 的 YAML似乎在结构上与 the other API definitions 的 YAML 相同
- 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 的绿色行:
最佳答案
您的 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: []
关于rest - Swagger UI 3 中出现奇怪的 "Could not resolve reference: undefined Not Found"消息,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/65584131/