【问题标题】:How can I override example in openapi spec?如何覆盖 openapi 规范中的示例?
【发布时间】:2021-06-24 23:23:53
【问题描述】:

我有以下规格:

---
openapi: 3.0.0
info:
  title: Players API
  version: 0.0.1-alpha1

paths:
  /players/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PlayerWrapper'
components:
  schemas:
    PlayerWrapper:
      type: object
      properties:
        display_name:
          type: string
          example: 76ers
        config:
          description: |
            The configuration of the player.
          example: { spec: { team: 76ers, names: [ 1, 2 ] } }
          allOf:
            - $ref: '#/components/schemas/Player'
    Player:
      type: object
      properties:
        spec:
          allOf:
            - $ref: '#/components/schemas/BasicPlayer'
      additionalProperties: false
    BasicPlayer:
      type: object
      properties:
        team:
          type: string
        names:
          allOf:
            - $ref: '#/components/schemas/Names'
      additionalProperties: false
    Names:
      type: array
      items:
        type: string
      example: [ Ben, Joel ]

我确实在Swagger 上验证了它确实有效。问题是为什么我可以看到names: [ 1, 2 ] 而不是[ Ben, Joel ]。当我删除 example 的东西 (# example: { spec: { team: 76ers, names: [ 1, 2 ] } }) 时,我可以看到 Ben, Joel 示例:

有没有办法强制覆盖/合并这些示例?截至目前,我觉得我的示例被这些字段中的任何一个(即 76ers / [1, 2] 或 string / [Ben, Joel] 但我想得到 76ers / [Ben, Joel] 代替)。

【问题讨论】:

    标签: swagger openapi


    【解决方案1】:

    您的架构中的结构不太正确。我们的想法是提供简单类型(字符串、int 等)的示例,并且架构将根据需要对其进行结构化。

    所以不要把例子放在配置上,把它放在像这样的嵌套简单类型上,即BasicPlayer对象应该在团队中有example,因为它是一个字符串:

        BasicPlayer:
          type: object
          properties:
            team:
              type: string
              example: '76ers'
            names:
              allOf:
                - $ref: '#/components/schemas/Names'
    

    与PlayerWrapper.config 类似,不要尝试在示例中给出完整的对象,它由成员属性组成。所以team 得到了一个例子,但Names 例子是由子类型组成的。

        PlayerWrapper:
          type: object
          properties:
            display_name:
              type: string
              example: '76ers'
            config:
              description: |
                The configuration of the player.
              allOf:
                - $ref: '#/components/schemas/Player'
    

    这应该给你预期的例子:

    这是完整的招摇:

    ---
    openapi: 3.0.0
    info:
      title: Players API
      version: 0.0.1-alpha1
    
    paths:
      /players/{id}:
        get:
          parameters: 
            - $ref: '#/components/parameters/id'
          responses:
            '200':
              description: OK
              content:
                application/json:
                  schema:
                    allOf:
                      - $ref: '#/components/schemas/PlayerWrapper'
    components:
      parameters:
        id: 
          name: id
          in: path
          required: true
          schema:
            type: string
          description: The id.
      schemas:
        PlayerWrapper:
          type: object
          properties:
            display_name:
              type: string
              example: '76ers'
            config:
              description: |
                The configuration of the player.
              allOf:
                - $ref: '#/components/schemas/Player'
        Player:
          type: object
          properties:
            spec:
              allOf:
                - $ref: '#/components/schemas/BasicPlayer'
          additionalProperties: false
        BasicPlayer:
          type: object
          properties:
            team:
              type: string
              example: '76ers'
            names:
              allOf:
                - $ref: '#/components/schemas/Names'
          additionalProperties: false
        Names:
          type: array
          items:
            type: string
            example: 
              - Ben
              - Joel
    

    请注意,可以使用资源定义中的示例覆盖架构示例,如下所示:

    paths:
      /players/{id}:
        get:
          parameters: 
            - $ref: '#/components/parameters/id'
          responses:
            '200':
              description: OK
              content:
                application/json:
                  schema:
                    allOf:
                      - $ref: '#/components/schemas/PlayerWrapper'
                  example:
                    display_name: 76ers
                    config:
                      spec:
                        team: 76ers
                        names:
                          - 'Ben'
                          - 'Joel'
    

    【讨论】:

      猜你喜欢
      • 1970-01-01
      • 2020-05-29
      • 2023-02-16
      • 1970-01-01
      • 1970-01-01
      • 1970-01-01
      • 1970-01-01
      • 2021-05-27
      • 1970-01-01
      相关资源
      最近更新 更多