Apicurio Registry用CURL上传OpenAPI制品后Documentation标签页为空的原因问询

核心原因 #

UI上传时，前端会自动校验OpenAPI内容格式、按要求把纯OpenAPI文档作为请求体发给Registry，所以能正常被解析生成Documentation。而CURL方式下出现Documentation为空，本质是请求的实际传输内容不满足Apicurio Registry的OpenAPI解析要求，Registry无法从上传内容中提取可渲染的结构化文档信息，常见触发场景包括：

• 请求体传值结构错误：当前命令中--data "{$body}"的写法存在明显问题，要么会因为手动拼接大括号给合法OpenAPI内容增加无效结构，要么会因为shell转义问题损坏内容格式，甚至会把OpenAPI字符串嵌套在外层JSON的某个字段里，没有遵循Registry要求的「请求体本身就是纯OpenAPI文档」的格式，解析器读不到根节点的info、接口描述等核心内容，自然无法生成Documentation页。
• 请求头和实际内容格式不匹配：如果上传的是YAML格式的OpenAPI文档，但请求头固定写了Content-type: application/json，解析器会直接按JSON规则解析YAML内容，直接触发解析失败，无法提取任何文档信息。
• OpenAPI文档本身存在结构缺陷：如果文档本身有语法错误、根节点缺失info字段、接口定义没有可识别的描述文本，即使上传成功，也没有可渲染到Documentation页的有效内容。

对应解决方案 #

• 修正请求体传值方式，优先用文件引用的方式传入本地的合法OpenAPI文件，不要手动拼接带转义的字符串，也不要在OpenAPI内容外层额外套大括号或嵌套结构，确保请求体本身就是完整、合规的OpenAPI文档结构。
• 根据实际上传的OpenAPI格式匹配Content-type请求头：JSON格式OpenAPI使用application/json，YAML格式OpenAPI使用application/x-yaml，避免格式不匹配导致解析失败。
• 上传完成后先校验制品实际存储的内容：切到制品详情的「内容」标签页，对比页面显示的内容和本地的OpenAPI文档是否完全一致，如果内容被截断、结构异常，就调整上传命令直到内容匹配。

修正后的参考CURL命令（以上传本地JSON格式OpenAPI文件为例）：

curl -X POST \
  -H "Content-type: application/json" \
  -H "X-Registry-ArtifactType: OPENAPI" \
  -H "X-Registry-ArtifactId: test" \
  --data @./openapi-spec.json \
  http://registry:8080/api/artifacts

内容的提问来源于stack exchange，提问作者Timur