33

So I understand that if we want body parameters we have to have a schema, which I do. The issue is no matter how I try to define my schema it does not allow me to have multiple body parameters. Here is an example of one of the methods I have tried. Any help would be great!

swagger: '2.0'

# This is your document metadata
info:
  version: "0.0.1"
  title: Todo App
schema: {
        }
host: localhost:3000
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/x-www-form-urlencoded
basePath: /

paths:
  # This is a path endpoint. Change it.
  /tasks:
    post:
      description: |
        Add 'Task' object.

      parameters:
        # An example parameter that is in query and is required
        -
          name: name 
          in: query
          description: unique object task name
          required: true
          schema:
            type: string
        - name: description
          in: query
          description: task description
          required: true
          schema:
            type: string

      responses:
        # Response code
        200: 
          description: Successful response
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
              title: Return String
              type: string
              example: "Task added succesfully"
        500:
          description: Error
          schema: 
            type: string
            example: "Could not add Task"
Jacob Brauchler
  • 579
  • 2
  • 7
  • 22

2 Answers2

40

I'm not sure to understand your question...

  • If you are trying to define more than one body parameter for one operation, you can't. As explained in swagger specification:

Body [...] there can only be one body parameter

  • If you are trying to send a body with multiple parameters, add an object model in the definitions section and refer it in your body parameter, see below (works with editor.swagger.io):

Your example nodes also are wrong, see here for more details.

swagger: '2.0'
info:
  version: "0.0.1"
  title: Todo App
host: localhost:3000
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/x-www-form-urlencoded
basePath: /
paths:
  # This is a path endpoint. Change it.
  /tasks:
    post:
      description: |
        Add 'Task' object.
      parameters:
        - name: task 
          in: body
          description: task object
          required: true
          schema:
            $ref: '#/definitions/Task'
      responses:
        200:
          description: Successful response
          schema:
              title: Return String
              type: string
              example: "Task added succesfully"
        500:
          description: Error
          schema: 
            type: string
            example: "Could not add Task"
definitions:
  Task:
    description: Task object
    properties:
      name:
        type: string
        description: task object name
      description:
        type: string
        description: task description
    required:
      - name
      - description
fabpico
  • 2,628
  • 4
  • 26
  • 43
Nelson G.
  • 5,145
  • 4
  • 43
  • 54
  • Thank you for your answer. But do you know what this error means? { "message": "Could not update task. ValidationError: Validator \"required\" failed for path name, Validator \"required\" failed for path description" } – Jacob Brauchler Jun 24 '15 at 19:54
  • 1
    How do you get this error? Could you describe your context ? – Nelson G. Jun 24 '15 at 20:30
  • It happens when I try to do a test of my function, with the example you used but for a put function, everything seemed to work right and then when I attempted to test I received that error. – Jacob Brauchler Jun 24 '15 at 20:53
  • 1
    I think called server expects a required field called 'name' and another called 'description'. Could you provide more information about server: techno? request model ? If swagger file is not compliant with expected request, server will reject all requests. – Nelson G. Jun 24 '15 at 21:02
  • I find this contradictory, looking at http://orange-opensource.github.io/angular-swagger-ui/ `/pet/{petID}/` has many! The definition defines them as `"in": "formData"`. Having tried that it worked! – Ian Vaughan Dec 16 '15 at 19:44
  • What I'd like to do though is reuse a schema definition! `$ref: '#/definitions/Foo'`, instead of having to list them all! – Ian Vaughan Dec 16 '15 at 19:51
8

You can also define the properties of the request body parameter using properties as part of its schema. This has a good example under Object Payload: https://swagger.io/docs/specification/2-0/describing-request-body/. 

paths:
  /users:
    post:
      summary: Creates a new user.
      consumes:
        - application/json
      parameters:
        - in: body
          name: user
          description: The user to create.
          schema:
            type: object
            required:
              - userName
            properties:
              userName:
                type: string
              firstName:
                type: string
              lastName:
                type: string
      responses:
        201:
          description: Created

The disadvantage of course is that you don't get the reuse of an object definition, but sometimes an object definition isn't appropriate.

GabeV
  • 859
  • 8
  • 21