Swagger YAML Query (тип объекта) Ошибка определения параметра

Question

Я получаю следующую ошибку:

Ошибка схемы в paths./cards/count.get.parameters[0] не совсем одна из <# / Definitions / Параметр>,<# / Definitions / jsonReference>

Вот мое определение:

  /cards/count:
    get:
      tags:
      - "cards"
      summary: "Number of Cards available"
      description: "Excludes cards which the user has answered correctly in the past."
      operationId: "countCards"
      produces:
      - "application/json"
      parameters:
      - name: "tagFilter"
        in: "query"
        description: "Input is optional - left blank will return all tags and a count"
        type: "object"
        properties:
          tags_any:
            type: "array"
            items:
              type: "integer"
              format: "int64"
              enum: [1,2,3]
          tags_all:
            type: "array"
            items:
              type: "integer"
              format: "int64"
              enum: [4,5,6]
          tags_not:
            type: "array"
            items:
              type: "integer"
              format: "int64"
              enum: [4,5,6]

Я понимаю, что вы не можете использовать определение схемы согласно этому вопросу: Swagger: Повторное использование определения enum в качестве параметра запроса

Что мне нужно изменить, чтобы компилировать YAML без ошибок?

Answer 1

Объекты в параметрах запроса не поддерживаются в OpenAPI/Swagger 2.0, но поддерживаются в OpenAPI 3.0.

Если вы придерживаетесь OpenAPI 2.0, вам нужно разделить объект на отдельные параметры, например:

      parameters:
        - in: query
          name: tags_any
          type: array
          items:
            type: integer
            format: int64
            enum: [1,2,3]
        - in: query
          name: tags_all
          type: array
          items:
            type: integer
            format: int64
            enum: [4,5,6]
        - in: query
          name: tags_not
          type: array
          items:
            type: integer
            format: int64
            enum: [4,5,6]

В OpenAPI 3.0 вы можете определить параметр как объект и использовать style а такжеexplode ключевые слова, чтобы указать, как этот объект должен быть сериализован.

      parameters:
        - name: tagFilter
          in: query
          description: Input is optional - left blank will return all tags and a count

          # Send the object as ?prop1=value1&prop2=value2
          # This is the default serialization method for objects in query parameters
          style: form
          explode: true

          schema:
            type: object
            properties:
              tags_any:
                type: array
                items:
                  type: integer
                  format: int64
                  enum: [1,2,3]
              tags_all:
                type: array
                items:
                  type: integer
                  format: int64
                  enum: [4,5,6]
              tags_not:
                type: array
                items:
                  type: integer
                  format: int64
                  enum: [4,5,6]