Swagger示例属性隐藏所有其他属性

Question

我正在swaggerhub上写一个malloc定义。有一个选项可以在多个Swagger中共享模型。招摇完成后，可以选择下载已导入链接定义的已解决的Swagger。

我的问题是，已解决的下载问题为模型添加了Unsafe.freeMemory节点，无论出于何种原因，当我们再次在编辑器中复制此新Swagger时，该节点都会覆盖每个属性。

假设我们有以下示例

Swagger

以下是其在example中的显示方式，

这是正确的方法，但是当我在模型--- swagger: "2.0" info: description: "" version: 1.0.0 title: title host: "example.com" basePath: / schemes: - http consumes: - application/json produces: - application/json paths: /test-service: post: tags: - test-service operationId: test-service parameters: - in: body name: body description: body required: true schema: $ref: '#/definitions/A' responses: 201: description: success schema: $ref: '#/definitions/A' definitions: A: type: object properties: a1: type: string a2: type: string 中有一个示例节点时，UI中仅显示示例属性，

这是我指的是

Swagger UI

现在，如果我在编辑器中导入此更改，则仅缺少属性A和 A: type: object properties: a1: type: string a2: type: string example: ex1: Hello ex2: World 以及实际属性ex1和ex2。

继承后，问题会更加严重。

发生的事情是，层次结构中哪一个最低的节点仅具有a1属性，这些属性仅显示在用户界面中，而不显示所有属性

这是示例无线

现在让我们在a2中引入example属性。在任何级别添加example属性后，所有其他属性都将被忽略。

这是C属性文档https://swagger.io/docs/specification/2-0/adding-examples/的链接。

没有关于这种奇怪行为的描述。

Answer 1

example就是这样工作的。引用OpenAPI 2.0 Specification：

  

此模式实例的自由形式...示例。

也就是说，example是整个架构的示例 。这就是按原样显示架构级别example的原因。它会覆盖所有属性级别的示例，并且不会自动包含example中未包含的属性。

在上一个带有allOf的示例中，A的架构等效于

definitions:
  A:
    type: object
    properties:
      a1:
        type: string
      a2:
        type: string
      b1:
        type: string
      b2:
        type: string
      c1:
        type: string
      c2:
        type: string
    example:
      ex1: Hello
      ex2: world

这也是为什么example中的模式级C会覆盖所有其他内容的原因。

您可能想使用属性级别的示例代替

：

definitions:
  A:
    type: object
    properties:
      a1:
        type: string
        example: Hello   # <---
      a2:
        type: string
        example: world   # <---