How to describe this POST JSON request body in OpenAPI (Swagger)?

Question

I have a POST request that uses the following JSON request body. How can I describe this request body using OpenAPI (Swagger)?

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

So far I tried the following, but I'm stuck at defining the body 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"              } 

I want to define the input body inline, as a sample for documentation.

Answer 1

I made it work with:

    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

The most readable way to include a multi line scalar into YAML is by using the block literal style. This requires you to change your JSON example only by using indentation (which will be removed if you retrieve the value for the key):

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

(for clarity you can put an extra newline or two before the paths scalar key, they get clipped by default on the literal block style scalars.