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

Question

我在Swagger上写了一个swaggerhub定义。有一个选项可以在多个Swaggers之间共享模型。在swaggers完成后，可以选择下载已导入链接定义的已解析Swagger。

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

假设我们有以下样本

---
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

以下是它在Swagger UI中的显示方式，

这是正确的方法，但是当我在模型A中有一个示例节点时，UI中只显示示例属性，

这是我所指的变化

  A:
    type: object
    properties:
      a1:
        type: string
      a2:
        type: string
    example:
      ex1: Hello
      ex2: World

现在，如果我在编辑器中导入此更改，则只缺少属性ex1和ex2以及实际属性a1和a2。

当我们有继承时，问题就会恶化。

发生的情况是，层次结构中最低的节点具有example属性，仅列出的属性在UI中显示，而不是显示所有属性

这是一个样本wi

现在让我们在example中介绍C属性。在任何级别添加example属性后，将忽略所有其他属性。

这是example属性文档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   # <---