如何在Swagger中同时保留表单键值对与新增对象参数？

Since you're working with Swagger 2.0 (evidenced by consumes, formData parameters, and definitions), here's how you can add the member object parameter while retaining your original username and email form fields:

Option 1: Nested Form Fields (Recommended for Form-Encoded Data) #

In application/x-www-form-urlencoded, nested objects are typically represented using bracket notation (e.g., member[name], member[email]). You can add these as separate formData parameters, and link them to your existing member definition for clarity.

Here's the updated Swagger snippet:

post:
  tags:
    - "users"
  summary: "Create User"
  operationId: "createUser"
  consumes:
    - "application/x-www-form-urlencoded"
  parameters:
    - name: "username"
      in: "formData"
      description: "Name of User"
      required: true
      type: "string"
    - name: "email"
      in: "formData"
      description: "Email"
      required: true
      type: "string"
    # Add nested fields for the member object
    - name: "member[name]"
      in: "formData"
      description: "Name of the member"
      required: false # Adjust based on your requirements
      type: "string"
    - name: "member[email]"
      in: "formData"
      description: "Email of the member"
      required: false # Adjust based on your requirements
      type: "string"
definitions:
  member:
    type: "object"
    properties:
      name:
        type: string
      email:
        type: string

This aligns with standard form-encoded practices—clients will send data as key-value pairs like:
username=johndoe&email=john@example.com&member[name]=janedoe&member[email]=jane@example.com

Option 2: Pass member as a JSON String #

If you need to send the entire member object as a single JSON string in form data, define a formData parameter of type string with format: json, and reference your member definition using schema:

post:
  tags:
    - "users"
  summary: "Create User"
  operationId: "createUser"
  consumes:
    - "application/x-www-form-urlencoded"
  parameters:
    - name: "username"
      in: "formData"
      description: "Name of User"
      required: true
      type: "string"
    - name: "email"
      in: "formData"
      description: "Email"
      required: true
      type: "string"
    # Add member as a JSON string parameter
    - name: "member"
      in: "formData"
      description: "Member object (as JSON string)"
      required: false # Adjust based on your requirements
      type: "string"
      format: "json"
      schema:
        $ref: "#/definitions/member"
definitions:
  member:
    type: "object"
    properties:
      name:
        type: string
      email:
        type: string

Clients would send the member value as a URL-encoded JSON string, e.g.:
username=johndoe&email=john@example.com&member=%7B%22name%22%3A%22janedoe%22%2C%22email%22%3A%22jane%40example.com%22%7D

Key Notes #

• Swagger 2.0 doesn't support directly defining nested objects as formData parameters—you have to use either the nested field approach or the JSON string approach.
• If you were using OpenAPI 3.0+, you could use requestBody with content/application/x-www-form-urlencoded and a schema that includes both top-level fields and the nested member object, but since your existing spec is Swagger 2.0, the above options are your best bets.

内容的提问来源于stack exchange，提问作者Gobliins