swagger: requestBody not allowed

问题:

I'm trying to define a post endpoint using swagger, but it isn't allowing the requestBody parameter:

  /names/{roster}:
    get:
      #...
    post:
      x-swagger-router-controller: names
      description: Adds or removes name(s)
      operationId: manageNames
      parameters:
      - name: roster
        in: path
        description: the roster to use
        type: string
        required: true
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/definitions/ManageNamesRequest'

when I run npm start, I get this:

API Errors:

  #/paths/~1names~1{roster}/post: Additional properties not allowed: requestBody

1 error and 0 warnings

What's wrong with my spec?

回答1:

You are probably mixing OpenAPI/Swagger 2.0 and OpenAPI 3.0 syntax. Your spec seems to be 2.0, but the requestBody keyword is a 3.0 feature. In 2.0, the request body is defined as a body parameter:

paths:
  /names/{roster}:
    post:
      produces:
        - application/json
      ...
      parameters:
      - ...
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/ManageNamesRequest'

More info: Describing Request Body