How to describe this POST JSON request body in OpenAPI (Swagger)? - 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.

Answer 3

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
...