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

Question

我的服务提供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 -->

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

Answer 1

这取决于你使用的是哪个版本的OpenAPI。

OpenAPI 3.1

externalValue可以是任意有效的URI。这包括相对引用。参见3.1文档。

OpenAPI 3.0

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

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

---

swagger-ui错误告诉你没有使用命名元素。试着提供一个名称。(请注意，该工具有bug，不能正确支持所有有效的OpenAPI设计。例如，这个相关的错误。)

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