Request samples

[andyslack]

Hi There,

Is there a way to include an example Request sample?

I am including example response but would be great to show an example request, so rather than:

{
"id": 0,
"status": "string",
"currency": "string",
"date_modified": { },
"discount_total": 0,
"shipping_total": 0,
"total_tax": 0,
"total": 0,
"billing": { },
"shipping": { },
"payment_method": "string",
"transaction_id": "string",
"customer_note": "string",
"meta_data": { },
"line_items": [ ],
"coupons": [ ],
"shipping_method": "string"
}

It could be something like:

{
"id": "AS0001",
"status": "processing",
"currency": "USD",
"date_modified": {
"date": "2021-03-19 12:32:55",
"timezone_type": 1,
"timezone": "+00:00"
},
"discount_total": 0,
"discount_tax": 0,
"shipping_total": 0,
"shipping_tax": 0,
"cart_tax": 0,
"total": 0.99,
"total_tax": 0,
"billing": {
"company": "Shoreline Lake American Bistro",
"first_name": "Andrew",
"last_name": "Slack",
"address_1": "3160 N Shoreline Blvd",
"address_2": "",
"city": "Mountain View",
"postcode": "94043",
"state_name": "CA",
"country": "US",
"email": "andy.slack@moreniche.com"
},
"shipping": {
"company": "Shoreline Lake American Bistro",
"first_name": "Andrew",
"last_name": "Slack",
"address_1": "3160 N Shoreline Blvd",
"address_2": "",
"city": "Mountain View",
"postcode": "94043",
"state_name": "CA",
"country": "US",
"email": "andy.slack@moreniche.com"
},
"payment_method": "",
"transaction_id": 0,
"customer_note": "",
"meta_data": { },
"line_items": [
{}
],
"coupons": [ ],
"shipping_method": "Standard Shipping"
}

[bourdakos1]

If it's possible in standard OpenAPI, it should be possible with this, but I'm not sure what it would look like. I will poke around

[bourdakos1]

I'm not sure exactly what you are looking for but you might be able to use @bodyComponent

[andyslack]

Hi @bourdakos1

Lets say I want to POST some JSON to an endpoint, e.g.

https://api.juicyllama.com/#tag/Webhook/paths/~1webhook/post

I can show the example response:

     * @responseContent {Webhook} 201.application/json
     * @responseExample {WebhookExample} 201.application/json.WebhookExample

Full comment:

 /**
     * POST /webhook
     * @queryParam {string} app_id - Your application ID
     * @queryParam {string} app_api_key - Your application API Key
     * @queryParam {string} admin_api_key - Your applications admin API Key
     * @bodyContent {WebhookPost} application/json
     * @bodyRequired
     * @tag Webhook
     * @summary Create Webhook
     * @description Create a new item
     * @response 201 - Created
     * @responseContent {Webhook} 201.application/json
     * @responseExample {WebhookExample} 201.application/json.WebhookExample
     * @response 400 - Bad request - Check you are passing all the required params
     * @response 401 - Authorization
     * @response 500 - Unexpected error.
     */

As you can see I included the bodyContent {WebhookPost} but I cannot see how to add the JSON example or the values to the YAML.

Here are my entries from the YAML file:

Schemas:

    Webhook:
      type: object
      properties:
        webhook_id:
          type: integer
          description: The record ID.
        app_id:
          type: integer
          description: Your App ID.
        url:
          type: string
          description: The url of your webhook
        resources:
          type: array
          description: The resources the webhook will fire on
        created_at:
          type: datetime
          description: The datetime the item was created
        updated_at:
          type: datetime
          description: The datetime the item was last updated
    WebhookPost:
      type: object
      required:
        - url
        - resources
      properties:
        url:
          type: string
          description: The url of your webhook
        resources:
          type: array
          description: The resources the webhook will fire on

examples:

 WebhookExample:
      value: {
        "webhook_id": 1,
        "app_id": 1,
        "url": "http://test.com/webhooks/example",
        "resources": [
            "post",
            "wall"
        ],
        "created_at": "2000-01-01 00:00:00",
        "updated_at": "2000-01-01 00:00:00"
      }

I hope this clarifies what I am looking to achieve.

[bourdakos1]

Using @bodyContent {WebhookPost} application/json only injects the schema and doesn't support an example:

requestBody:
    content:
        application/json:
            schema: <{WebhookPost} get's injected here>
            example: <this doesn't get set>

you can use @bodyComponent {WebhookPostBody} instead for more control. Under the hood it looks like this:

requestBody:
    $ref: <{WebhookPostBody} get's injected here>

example body component:

components:
  requestBodies:
    WebhookPostBody:
      description: xxxx
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookPost'
          examples:
            $ref: '#/components/examples/Webhook'

[andyslack]

Amazing, I managed to get this working after a little jiggery pokery. Thank you SO much for your help!

[bourdakos1]

Awesome! No problem 😊