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

openapi version >= 3.0.0 allows for the use of a requestBody which would allow for request body definitions outside of parameters.

In your case it would look something like this:

...
      requestBody:
        description: The pet JSON you want to post
        required: true
        content:
          application/json:
            schema:
              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
              example:
                testapi:
                  testapiContext:
                    messageId: kkkk8
                    messageDateTime: '2014-08-17T14:07:30+0530'
                  testapiBody:
                    cameraServiceRq:
                      osType: android
                      deviceType: samsung555
...

Answer 2

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 3

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.