如何在OpenAPI中定义多响应体Schema并解决校验报错？

你的OpenAPI文档存在几个关键问题，下面是修正后的完整代码，以及对应的问题说明：

修正后的OpenAPI 3.0.1文档 #

openapi: 3.0.1
info:
  title: 员工信息API
  description: >-
    abc系统的REST API
  contact:
    name: ABC团队
    email: abc@example.com
  version: "1.0.0"
servers:
  - url: "http://localhost:8080/"
tags:
  - name: 员工信息
    description: 获取员工相关信息
paths:
  /Employees:
    get:
      description: 根据条件获取员工信息，可选参数`cond`控制响应结构
      summary: 获取员工信息
      tags:
      - 员工信息
      security:
      - basicAuth: []
      operationId: GetEmployees
      parameters:
      - name: EmpNbr
        in: query
        description: 员工ID（示例：0123456789）
        required: true
        schema:
          type: string
      - name: DateofJoin
        in: query
        description: 入职日期（示例：mmddyyyy格式，如01012023）
        required: true
        schema:
          type: string
      - name: cond
        in: query
        description: 额外条件，传入时返回带根节点的响应结构
        required: false
        schema:
          type: string
          allowEmptyValue: true
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Employees'
                  - $ref: '#/components/schemas/Employeewithroot'
components:
  schemas:
    Employeewithroot:
      type: object
      properties:
        Employee:
          type: array
          items:
            $ref: '#/components/schemas/Employees'
          x-go-name: Employees
    Employees:
      type: object
      properties:
        EmpNbr:
          $ref: '#/components/schemas/NullString'
        DateofJoin:
          $ref: '#/components/schemas/NullString'
        DeptId:
          $ref: '#/components/schemas/NullString'
        DeptName:
          $ref: '#/components/schemas/NullString'
      x-go-package: pkg/model
    NullString:
      type: object
      properties:
        String:
          type: string
        Valid:
          type: boolean
      description: 支持空值的字符串类型，对应Go的sql.NullString
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

关键修改说明 #

1. 修复「路径不得包含查询字符串」错误 #

• 原文档错误地将带查询参数的URL拆分为独立路径，OpenAPI规范要求路径仅定义基础路径，所有查询参数必须在parameters数组中声明。
• 修正后：将所有查询参数（包括新增的cond）统一放在/Employees的get操作的parameters里，cond设为非必填参数，通过它控制响应结构。

2. 修复「检测到可能未使用的组件」错误 #

• 原文档引用了#/components/schemas/NullString但未定义该组件，导致校验报错。
• 补充定义NullString schema，对应Go中的sql.NullString结构，包含String和Valid两个字段。

3. 修正响应结构定义 #

• 原文档中带cond参数时的响应错误定义为数组类型，实际返回的是包含Employee数组的对象。
• 使用oneOf关键字声明两种可能的响应结构：未传cond时返回Employees数组，传参时返回Employeewithroot对象，匹配实际接口逻辑。

4. 其他细节优化 #

• 修复security配置语法错误：将basicAuth: ['[]']改为basicAuth: []，符合OpenAPI规范。
• 修正securitySchemes类型：Basic认证应使用http类型并指定scheme: basic，而非原错误的apiKey类型。
• 为Employees和Employeewithroot补充type: object声明，确保schema结构完整。

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