Редактор Swagger несколько параметров в теле

Question

Итак, я понимаю, что если мы хотим иметь параметры тела, мы должны иметь схему, которую я делаю. Проблема в том, как я пытаюсь определить мою схему, она не позволяет мне иметь несколько параметров тела. Вот пример одного из методов, которые я пробовал. Любая помощь будет замечательной!

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" 

Answer 1

Я не уверен, чтобы понять ваш вопрос ...

• Если вы пытаетесь определить параметр больше, чем один тела за одну операцию, вы не можете. Как объяснялось в swagger specification:

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

• Если вы пытаетесь отправить тело с несколькими параметрами, добавить вы объектной модели в разделе определений и передать его в вас параметр тела, смотрите ниже (работает с editor.swagger.io:

Вы примеры узлы также являются неправильными, см here для более подробной информации.

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 

Answer 2

Вы также можете определить свойства параметра тела запроса, используя properties как часть своего schema. Это хороший пример в разделе «Полезная нагрузка объекта»: 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 

Недостаток, конечно, что вы не получите повторное использование определения объекта, но иногда определение объекта не подходит.