Написать документ swagger, который использует несколько типов контента, например application/json AND application/x-www-form-urlencoded (без дублирования)

Question

Я ищу элегантный способ определения API, который может использовать данные JSON, а также данные формы. Следующий фрагмент кода работает, но он не элегантен и требует всего вида уродливого кода в бэкэнде. Есть ли лучший способ определить это?

Что работает прямо сейчас:

paths:
  /pets:
    post:
      consumes:
      - application/x-www-form-urlencoded
      - application/json
      parameters:
      - name: nameFormData
        in: formData
        description: Updated name of the pet
        required: false
        type: string
      - name: nameJSON
        in: body
        description: Updated name of the pet
        required: false
        type: string

Основная идея, как я хотел бы, чтобы это работало:

paths:
  /pets:
    post:
      consumes:
      - application/x-www-form-urlencoded
      - application/json
      parameters:
      - name: name
        in: 
        - formData
        - body
        description: Updated name of the pet
        required: true
        type: string

Но это не работает, потому что in значение должно быть строкой, а не массивом.

Есть хорошие идеи?

Answer 1

В OpenAPI 2.0 нет способа описать это. Параметры формы и тела являются взаимоисключающими, поэтому операция может иметь либо данные формы, либо тело JSON, но не оба одновременно. Возможный обходной путь - это иметь две отдельные конечные точки - одну для данных формы и другую для JSON - если это приемлемо в вашем сценарии.

Тем не менее, это будет возможно в OpenAPI 3.0 (который является RC на момент написания). 3.0 вводит requestBody ключевое слово, которое используется для определения возможных типов контента, поэтому мы сможем application/json а также application/x-www-form-urlencoded в одной операции. Разные типы контента могут иметь одну и ту же схему или разные схемы.

Когда выйдет 3.0 и обновится инструментарий, ваш пример можно описать следующим образом:

paths:
  /pets:
    post:
      requestBody:
        required: true
        content:

          application/json:
            schema:
              $ref: '#/components/schemas/Pet'

          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'

       responses:
         '200':
            description: OK

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
          description: Updated name of the pet
      required:
        - name

Дополнительная информация:

• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#support-for-x-www-form-urlencoded-request-bodies
• https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/