编写耗时的文档，其中包含多种内容类型，例如application/json和application/x-www-form-urlencoded(无重复) [英] Write swagger doc that consumes multiple content types e.g. application/json AND application/x-www-form-urlencoded (w/o duplication)

问题描述

我正在寻找一种定义可以同时使用JSON数据和表单数据的api的优雅方法.以下代码片段可以正常工作，但是它并不优雅，并且在后端需要各种难看的代码.有没有更好的方法来定义这个?

I'm looking for an elegant way to define an api that can consume JSON data as well as form data. The following snippet works, but it's not elegant and requires all kind of ugly code in the backend. Is there a better way to define this?

当前有效的方法:

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值必须是字符串，而不是数组.

But this doesn't work because the in value must be a string, not an array.

有什么好主意吗?

推荐答案

OpenAPI 2.0

在OpenAPI 2.0中，无法对此进行描述.表单和正文参数是互斥的，因此操作可以具有表单数据或JSON正文，但不能同时具有两者.一种可能的解决方法是，在您的方案中可以接受两个单独的端点-一个用于表单数据，另一个用于JSON.

OpenAPI 2.0

In OpenAPI 2.0, there's no way to describe that. Form and body parameters are mutually exclusive, so an operation can have either form data OR JSON body but not both. A possible workaround is to have two separate endpoints - one for form data and another one for JSON - if that is acceptable in your scenario.

可以使用OpenAPI 3.0描述您的方案. requestBody.content.<media-type>关键字用于定义该操作接受的各种媒体类型，例如application/json和application/x-www-form-urlencoded及其模式.媒体类型可以具有相同的架构或不同的架构.

Your scenario can be described using OpenAPI 3.0. The requestBody.content.<media-type> keyword is used to define various media types accepted by the operation, such as application/json and application/x-www-form-urlencoded, and their schemas. Media types can have the same schema or different schemas.

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

更多信息:

• OAS3:描述请求正文
• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#support-for-x-www-form-urlencoded-request-body
• https://blog. readme.io/an-example-filled-guide-to-swagger-3-2/#requestformat

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

这篇关于编写耗时的文档，其中包含多种内容类型，例如application/json和application/x-www-form-urlencoded(无重复)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！