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

Я ищу элегантный способ определить 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 должно быть строкой, а не массивом.

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


openapi swagger swagger-2.0 swagger-editor
person Scottmas    schedule 17.02.2017    source источник
comment
Это реальная проблема, надеюсь, есть решение, иначе вы могли бы открыть вопрос на их github.   -  person NodeNodeNode    schedule 14.03.2017
comment
Также заинтересован в том, чтобы сделать то же самое, хотя в моем случае, в частности, я хотел бы дать пользователям возможность загружать изображение в JSON/Base64, если они того пожелают.   -  person Matt    schedule 31.03.2017

Ответы (1)


arrow_upward
7
arrow_downward

OpenAPI 2.0

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

OpenAPI 3.0

Ваш сценарий можно описать с помощью OpenAPI 3.0. Ключевое слово requestBody.content.<media-type> используется для определения различных типов мультимедиа, принимаемых операцией, таких как application/json и application/x-www-form-urlencoded, и их схем. Типы носителей могут иметь одну и ту же схему или разные схемы.

openapi: 3.0.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

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

person Helen    schedule 11.04.2017