Support x-examples vendor extension for requests

[brendo]

This PR adds a vendor extension of x-examples which allows developers to specify an example for requests.

Right now a JSON example is automatically generated from the schema and this is an awesome feature most of the time, however we have a couple of cases where it would be ideal if we could specify an example (dealing with rather large schema 😞 ).

The value of x-examples is the same as the Example object from the specification, even though application/json (or something JSON-like with #225) is the only "valid" mime type for the time being.

[RomanHotsiy]

Hey@brendo! Have you just merged your other PR #225 into this?
If yes, close please #225. I am going to merge this and release a new version in the next 2-3hrs

[brendo]

Damn, sorry I did! That was unintentional but if you're happy with both feel free to merge this and I'll close the other!

[RomanHotsiy]

@brendo I have merged your PR. Thanks!
Do you need a fresh package to be released ?

[brendo]

Do you need a fresh package to be released ?

Only if it suits you, I'm running off a branch from here for now 👍

[sgilroy]

@brendo Can you provide an example of how to use x-examples? Looks like this might be a good solution for me. Thanks!

[brendo]

Sure @sgilroy, here's an example:

...
"/session": {
  "post": {
    "summary": "Create a session token.",
    "description": "Returns a session token that can authenticate Temando Platform requests. \n\nRequest a session token using `bearerToken` and `accountId`, or `email` and `password`.",
    "operationId": "Authenticate",
    "tags": [
      "Session"
    ],
    "consumes": [
      "application/vnd.api+json"
    ],
    "produces": [
      "application/vnd.api+json"
    ],
    "security": [],
    "parameters": [
      {
        "name": "credentials",
        "in": "body",
        "schema": {
          "$ref": "#/definitions/SessionRequest"
        },
        "x-examples": {
          "application/vnd.api+json": {
            "data": {
              "type": "session",
              "attributes": {
                "accountId": "sample-account-id-here",
                "bearerToken": "bearer-token-from-account-creation",
                "scope": "client"
              }
            }
          }
        }
      }
    ],
    "responses": {
      "201": {
        "description": "Credentials accepted and session token created.",
        "schema": {
          "$ref": "#/definitions/SessionResponse"
        },
        "examples": {
          "application/vnd.api+json": {
            "data": {
              "id": "edb3cd92-ab8c-4133-8997-ef8408015fc6",
              "type": "session",
              "attributes": {
                "session": "<redacted>",
                "expiry": 1488185868834
              }
            }
          }
        }
      },
      "401": {
        "description": "Authentication failed.",
        "schema": {
          "$ref": "#/definitions/Error"
        }
      },
      "403": {
        "description": "Expired credentials.",
        "schema": {
          "$ref": "#/definitions/Error"
        }
      },
      "500": {
        "description": "Unexpected error",
        "schema": {
          "$ref": "#/definitions/Error"
        }
      }
    }
  }
},
...

[sgilroy]

@brendo Thanks! Looking forward to seeing this supported in a release in the near future.

[bdentino]

This looks great! Any update on when it will be available in a release?

[RomanHotsiy]

@bdentino yes, today 🎉
Will let you know once I'm done

[RomanHotsiy]

@bdentino available in the version 1.12.0 ✅

[bdentino]

You're awesome! Thanks!