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

时间:2018-08-31 14:21:52

标签: swagger swagger-ui swagger-2.0

我正在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中仅显示示例属性,

Correctly displayed

这是我指的是

Swagger UI

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

Incorrectly displayed

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

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

这是示例无线Correctly displayed

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

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

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

Incorrectly displayed

1 个答案:

答案 0 :(得分: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   # <---