How to define Swagger 2.0 JSON to populate default body parameter object in Swagger UI?

Gabe picture Gabe · Nov 3, 2016 · Viewed 12k times · Source

Our current deployment patterns require me to manually write my swagger json output that will be consumed by the Swagger-based UI in use at my company. I'd like the json I'm writing to provide 'default' values to populate the Swagger UI for all input fields, including the body input parameter. My body parameter is a referenced object as seen below. How do I define the returned swagger JSON to auto populate the body portion of the request when the "Try this operation" is clicked?

An example Swagger spec that has no default/example data populated in the Swagger UI is below.

{
   "swagger":"2.0",
   "info":{
      "description":"Example API Description",
      "title":"Example Title",
      "version":"v3.0"
   },
   "tags":[
      {
         "name":"v3"
      }
   ],
   "consumes":[
      "application/json"
   ],
   "produces":[
      "application/json"
   ],
   "paths":{
      "/v3/api/{subscriptionID}/example":{
         "post":{
            "tags":[
               "v3"
            ],
            "description":"This API will do something",
            "consumes":[
               "application/json"
            ],
            "produces":[
               "application/json"
            ],
            "parameters":[
               {
                  "name":"Accept",
                  "in":"header",
                  "description":"The Accept request-header field can be used to specify the media types which are acceptable for the response. If not provided, the default value will be application/json",
                  "required":false,
                  "default":"application/json",
                  "type":"string"
               },
               {
                  "name":"Content-Type",
                  "in":"header",
                  "description":"The MIME type of the body of the request.  Required for PUT, POST, and PATCH, where a request body is expected to be provided.",
                  "required":true,
                  "default":"application/json; charset=utf-8",
                  "type":"string"
               },
               {
                  "name":"company_locale",
                  "in":"header",
                  "description":"The desired language as spoken in a particular region preference of the customer of this particular transaction.  Consists of two lower case language",
                  "required":true,
                  "default":"en_US",
                  "type":"string"
               },
               {
                  "name":"originatingip",
                  "in":"header",
                  "description":"The originating ip address of the calling device or browser.",
                  "required":true,
                  "default":"100.100.10.1",
                  "type":"string"
               },
               {
                  "name":"transaction_id",
                  "in":"header",
                  "description":"The transaction identifier for this invocation of the service.  ",
                  "required":true,
                  "default":"1e2bd51d-a865-4d37-9ac9-c345dc59119b",
                  "type":"string"
               },
               {
                  "name":"subscriptionID",
                  "in":"path",
                  "description":"The unique identifier that represents the subscribed portfolio of products.",
                  "required":true,
                  "default":"1e2bd51d",
                  "type":"string"
               },
               {
                  "name":"body",
                  "in":"body",
                  "description":"The body of the request",
                  "required":true,
                  "schema":{
                     "$ref":"#/definitions/exampleDefinition"
                  }
               }
            ],
            "responses":{
               "200":{
                  "description":"OK",
                  "headers":{
                     "transaction_id":{
                        "type":"string",
                        "default":"de305d54-75b4-431b-adb2-eb6b9e546013",
                        "description":"The identifier for the service transaction attempt."
                     }
                  }
               }
            }
         }
      }
   },
   "definitions":{
      "exampleDefinition":{
         "type":"object",
         "description":"Request details for Example Definition",
         "properties":{
            "action":{
               "type":"string",
               "description":"Specifies the action to be taken"
            },
            "applyToBase":{
               "type":"string",
               "description":"A boolean value that defines the behaviour of the request against the base"
            },
            "addOnIDs":{
               "type":"string",
               "description":"The identifiers for the add-ons"
            }
         },
         "required":[
            "action",
            "applyToBase",
            "addOnIDs"
         ]
      }
   }
}

I have been testing this json at http://editor.swagger.io/#/ by clicking File->Paste JSON.... I then click "Try this operation", scroll down and observe that the values of my body parameter are not populated - that's what I'd like to change.

Thanks in advance for any suggestions.

Answer

Arnaud Lauret picture Arnaud Lauret · Nov 4, 2016

To have example values, you just have to add an "example" property where needed:

exampleDefinition:
  type: object
  description: Request details for Example Definition
  properties:
    action:
      type: string
      description: Specifies the action to be taken
      example: An action value
    applyToBase:
      type: string
      description: >-
        A boolean value that defines the behaviour of the request against the base
      example: An apply to base value
    addOnIDs:
      type: string
      description: The identifiers for the add-ons
      example: an ID

Unfortunately the online editor don't propose them but SwaggerUI does: SwaggerUI