Как описать это тело запроса POST JSON в OpenAPI (Swagger)?

Question

У меня есть запрос POST, который использует следующий модуль запроса JSON. Как я могу описать этот орган запроса с помощью OpenAPI (Swagger)?

{ 
    "testapi": { 
     "testapiContext": { 
      "messageId": "kkkk8", 
      "messageDateTime": "2014-08-17T14:07:30+0530" 
     }, 
     "testapiBody": { 
      "cameraServiceRq": { 
       "osType": "android", 
       "deviceType": "samsung555" 
      } 
     } 
    } 
} 

До сих пор я попытался следующие, но я застрял в определении тела schema.

swagger: "2.0" 
info: 
    version: 1.0.0 
    title: get camera 
    license: 
    name: MIT 
host: localhost 
basePath: /test/service 
schemes: 
    - http 
consumes: 
    - application/json 
produces: 
    - application/json 
paths: 
    /getCameraParameters: 
    post: 
     summary: Create new parameters 
     operationId: createnew 
     consumes: 
     - application/json 
     - application/xml 
     produces: 
     - application/json 
     - application/xml 
     parameters: 
     - name: pet 
      in: body 
      description: The pet JSON you want to post 
      schema: # <--- What do I write here? 

      required: true 
     responses: 
     200: 
      description: "200 response" 
      examples: 
      application/json: 
      { 
       "status": "Success" 
      } 

Я хочу определить входной корпус inline, как образец для документации.

Answer 1

Я сделал это работать:

post: 
     consumes: 
     - application/json 
     produces: 
     - application/json 
     - text/xml 
     - text/html 
     parameters: 
     - name: body 
      in: body 
      required: true 
      schema: 
      # Body schema with atomic property examples 
      type: object 
      properties: 
       testapi: 
       type: object 
       properties: 
        messageId: 
        type: string 
        example: kkkk8 
        messageDateTime: 
        type: string 
        example: '2014-08-17T14:07:30+0530' 
       testapiBody: 
       type: object 
       properties: 
        cameraServiceRq: 
        type: object 
        properties: 
         osType: 
         type: string 
         example: android 
         deviceType: 
         type: string 
         example: samsung555 
      # Alternatively, we can use a schema-level example 
      example: 
       testapi: 
       testapiContext: 
        messageId: kkkk8 
        messageDateTime: '2014-08-17T14:07:30+0530' 
       testapiBody: 
        cameraServiceRq: 
        osType: android 
        deviceType: samsung555 

Answer 2

Наиболее читаемым способом включения многострочного скаляра в YAML является использование block literal style. Для этого необходимо изменить пример JSON только с помощью отступов (который будет удален, если вы извлекаете значение ключа):

. 
. 
produces: 
    - application/json 
example: | 
    { 
     "testapi": { 
      "testapiContext": { 
       "messageId": "kkkk8", 
       "messageDateTime": "2014-08-17T14:07:30+0530" 
    }, 
      "testapiBody": { 
       "cameraServiceRq": { 
        "osType": "android", 
        "deviceType": "samsung555" 
       } 
      } 
     } 
    } 
paths: 
    /getCameraParameters: 
. 
. 

(для ясности вы можете поставить дополнительный символ новой строки или два до скалярного ключа paths ., они получают clipped by default на буквальных скалярах блока стиля