Напишите документ с чаргом, который потребляет несколько типов контента, например. application/json И 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/#requestformat