Feature request: Sample request/response

[sudsk]

Hi,

Thanks for the great work on reDoc!
I have a request if its possible to introduce sample request/response. For example have a look at this url for Shopify's API reference - https://help.shopify.com/api/reference/transaction.
Same endpoint can support one or more request scenarios. Provide samples would provide complete client documentation. This could be a new section below Responses section for each endpoint. The content of samples can be provided as JSON or YAML objects.

A scenario is presented below from above shopify url.

Scenario - Capture a specified amount on a previously authorized order.

POST /admin/orders/#{id}/transactions.json

{
  "transaction": {
    "amount": "10.00",
    "kind": "capture"
  }
}

Hide Response
HTTP/1.1 201 Created

{
  "transaction": {
    "id": 1068278464,
    "order_id": 450789469,
    "amount": "10.00",
    "kind": "capture",
    "gateway": "bogus",
    "status": "success",
    "message": "Bogus Gateway: Forced success",
    "created_at": "2017-01-05T15:31:49-05:00",
    "test": true,
    "authorization": null,
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 389404469,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "755357713"
  }
}

[sudsk]

The way it could be written in swagger spec is, after the response section in spec we can have a section for sample request/response.

  responses:
    '201': ...........
    '4xx':.....
    '5xx':.....
  x-<app>-samples:
    - $ref: '#/x-<app>-samples/orders-capture-after-auth'

The at the bottom of model definition section we can define these:-

x-<app>-samples:
  orders-capture-after-auth:
    title: Capture a specified amount on a previously authorized order.
    description: This sample captures a specified amount on a previously authorized order.
    method: POST
    url: /admin/orders/#{id}/transactions.json
    Request: {
       "transaction": {
       "amount": "10.00",
       "kind": "capture"
    }
    Response: 
    HTTP/1.1 201 Created
    {
      "transaction": {
      "id": 1068278464,
      "order_id": 450789469,
      "amount": "10.00",
      "kind": "capture",
      "gateway": "bogus",
      "status": "success",
      "message": "Bogus Gateway: Forced success",
      "created_at": "2017-01-05T15:31:49-05:00",
      "test": true,
      "authorization": null,
      "currency": "USD",
      "location_id": null,
      "user_id": null,
      "parent_id": 389404469,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "755357713"
      }
}

[RomanHotsiy]

@suds123 ReDoc is more focused on Reference documentation and what you suggest is more like tutorials.
We have considered tutorials and we believe that this should not be a part of ReDoc lib. But I can help you to create a customized build for you.
Feel free to contact me (see email on my GitHub profile)

[RomanHotsiy]

Closing this for now as it's beyond the scope of the project