Search code examples
swaggerswagger-2.0openapi

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


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.


Solution

  • 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