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

【问题标题】：Can I add examples of file contents in OpenAPI specifications?我可以在 OpenAPI 规范中添加文件内容示例吗？
【发布时间】：2021-05-27 02:38:59
【问题描述】：

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

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

但是，swagger-ui 会产生无益的：

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

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

【问题讨论】：

标签： xml swagger-ui openapi

【解决方案1】：

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

OpenAPI 3.1

externalValue 可以是任何有效的 URI。这包括相对引用。请参阅3.1 documentation。

OpenAPI 3.0

externalValue 必须是有效的 URL。它不能是相对文件路径。见3.0 documentation。

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

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

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

【讨论】：

谢谢。我在 OpenAPI 3.0 中。但是，即使使用绝对 URI（请参阅更新的问题），该示例也不包含在 Swagger-ui 输出中。
我添加了一些您可以尝试的附加信息。