OpenAPI 3.0.0中如何共享POST参数与响应字段的描述？

核心需求实现思路 #

要让同一组字段既作为POST请求的一级参数，又能复用其定义作为响应返回结构，需通过components下的两个模块配合实现，避免字段嵌套。

具体实现方案 #

1. 先定义共享字段的Schema

在components/schemas里统一维护字段的类型、描述等信息，用于响应结构复用：

components:
  schemas:
    SharedRequestFields:
      type: object
      properties:
        username:
          type: string
          description: 用户登录名
        phone:
          type: string
          pattern: '^1[3-9]\d{9}$'
          description: 绑定手机号
        status:
          type: integer
          enum: [0, 1]
          description: 状态（0=禁用，1=启用）

2. 批量定义一级请求参数

在components/parameters中，将Schema里的每个字段单独定义为一级参数，确保请求时字段不嵌套：

components:
  parameters:
    UsernameParam:
      name: username
      in: formData  # 若为POST表单提交用formData，URL参数用query
      required: true
      schema:
        $ref: '#/components/schemas/SharedRequestFields/properties/username'
      description: '#/components/schemas/SharedRequestFields/properties/username/description'
    PhoneParam:
      name: phone
      in: formData
      schema:
        $ref: '#/components/schemas/SharedRequestFields/properties/phone'
      description: '#/components/schemas/SharedRequestFields/properties/phone/description'
    StatusParam:
      name: status
      in: formData
      schema:
        $ref: '#/components/schemas/SharedRequestFields/properties/status'
      description: '#/components/schemas/SharedRequestFields/properties/status/description'

3. 接口中引用参数与响应Schema

在POST接口里直接引用定义好的一级参数，响应则复用共享Schema：

paths:
  /user/info:
    post:
      parameters:
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/PhoneParam'
        - $ref: '#/components/parameters/StatusParam'
      responses:
        '200':
          description: 成功返回提交的所有参数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedRequestFields'

OpenAPI 3.1+简化方案 #

如果可以升级到3.1.0版本，支持用通配符直接展开Schema字段为一级参数，无需单独定义每个参数：

paths:
  /user/info:
    post:
      parameters:
        - in: formData
          name: '*'  # 通配符表示将Schema所有字段转为一级参数
          schema:
            $ref: '#/components/schemas/SharedRequestFields'
      responses:
        '200':
          description: 成功返回提交的所有参数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedRequestFields'

表单提交的特殊处理 #

如果是application/x-www-form-urlencoded类型的POST请求，可直接在requestBody里引用共享Schema，自动生成一级表单字段，无需单独定义参数：

paths:
  /user/info:
    post:
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SharedRequestFields'
      responses:
        '200':
          description: 成功返回提交的所有参数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedRequestFields'

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