部署GCP API Gateway出现body字段路径错误的原因及修复

这个错误是因为GCP API Gateway不允许请求体直接使用数组类型，它要求请求体必须是一个非重复的消息（也就是单个对象）——即便你的后端服务实际接收的是数组，网关层面也需要先把数组包裹在一个对象中。

Swagger Editor只会按照Swagger 2.0规范做校验，不会检测GCP API Gateway的私有限制，所以才会出现本地校验通过但部署失败的情况。

swagger: '2.0'
info:
  title: API Gateway
  version: 1.0.0
  description: API Gateway
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  firebase:
    scopes: {}
    authorizationUrl: ''
    flow: implicit
    type: oauth2
    x-google-issuer: 'https://securetoken.google.com/project-id'
    x-google-jwks_uri: 'https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com'
paths:
  '/v1/events/{id}/tickets':
    get:
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          required: true
          type: string
      responses:
        '200':
          description: ''
          schema:
            items:
              properties:
                description:
                  type: string
                donationPurpose:
                  type: string
                endDate:
                  format: date-time
                  type: string
                endTime:
                  type: string
                eventId:
                  type: string
                freeTicketType:
                  enum:
                    - donation
                    - infaq
                    - none
                  type: string
                id:
                  type: string
                name:
                  type: string
                price:
                  type: number
                startDate:
                  format: date-time
                  type: string
                startTime:
                  type: string
                totalAvailableTickets:
                  type: number
                totalTickets:
                  type: number
                type:
                  enum:
                    - free
                    - paid
                  type: string
              required:
                - id
                - eventId
                - name
                - description
                - type
                - freeTicketType
                - donationPurpose
                - totalAvailableTickets
                - totalTickets
                - price
                - startDate
                - endDate
                - startTime
                - endTime
              type: object
            type: array
      security:
        - firebase: []
      tags:
        - events
      operationId: EventController_getTicketsByEvent
      summary: Get event tickets
      x-google-backend:
        address: 'https://backend-et.a.run.app/v1/events/{id}/tickets'
    post:
      consumes:
        - application/json
      parameters:
        - in: path
          name: id
          required: true
          type: string
        - in: body
          name: ticketRequest
          required: true
          schema:
            type: object
            properties:
              tickets:
                type: array
                items:
                  type: string
            required:
              - tickets
      responses:
        '200':
          description: ''
      security:
        - firebase: []
      tags:
        - events
      operationId: EventController_createTicket
      summary: Create event tickets
      x-google-backend:
        address: 'https://backend-et.a.run.app/v1/events/{id}/tickets'
    put:
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: id
          required: true
          type: string
        - in: body
          name: updateTicketRequest
          required: true
          schema:
            type: object
            properties:
              updateTickets:
                type: array
                items:
                  type: string
            required:
              - updateTickets
      responses:
        '200':
          description: ''
        '404':
          description: ''
          schema:
            properties:
              error:
                properties:
                  data:
                    type: object
                  details:
                    type: object
                  errorCode:
                    type: number
                  errorName:
                    type: string
                  localizedMessage:
                    type: string
                  message:
                    type: string
                  path:
                    type: string
                  requestId:
                    type: string
                  status:
                    type: string
                  timestamp:
                    type: string
                required:
                  - status
                  - errorCode
                  - message
                  - errorName
                  - details
                  - path
                  - requestId
                  - timestamp
                  - data
                type: object
            required:
              - error
            type: object
      security:
        - firebase: []
      tags:
        - events
      operationId: EventController_updateTicket
      summary: Update event tickets
      x-google-backend:
        address: 'https://backend-et.a.run.app/v1/events/{id}/tickets'

• 针对post和put方法的body参数，将原本直接定义的数组类型包裹进一个对象中，新增了tickets和updateTickets作为数组属性
• 给body参数命名为更清晰的ticketRequest和updateTicketRequest，同时添加required字段确保核心属性存在
• 其余部分保持原配置不变，不影响现有功能

内容的提问来源于stack exchange，提问作者Muhammad Rafiul Ilmi S