我可以在OpenAPI规范中添加文件内容的示例吗？

Question

我的服务提供XML文件的上传。OpenApi规范没有指定模式。我想提供一个输入示例。我试试这个：

/foo:
    post:      
      requestBody:
        content: 
          application/xml:
            schema:
              type: string
              format: binary
              example:
                  externalValue: 'https://www.w3schools.com/xml/note.xml'

然而，大摇大摆的用户界面产生了无用的结果：

<!-- XML example cannot be generated; root element name is undefined -->

是否可以从外部文件中指定示例？

Answer 1

这取决于您使用的OpenAPI版本。

externalValue可以是任何有效的URI。这包括相对参考。请参阅3.1文档。

externalValue必须是有效的URL。它不能是相对文件路径。请参阅3.0文档。

将值更改为xml文件的托管位置。

swagger ui错误告诉您没有使用命名元素。尝试提供一个名称。（请注意，该工具存在bug，并且不能正确支持所有有效的OpenAPI设计。例如，此相关bug。）

examples:
  exampleName:
    summary: A sample object
    externalValue: 'https://www.w3schools.com/xml/note.xml'