Add examples support to requests

[kriston-costa]

A PR WITH EXAMPLE USAGE IS HERE: https://github.com/instacart/carrot/pull/155131

We want to add examples support to request bodies in Swagger. Right now our requests look like the following:

They just supply the type information in the field.

rswag does not support adding examples right now:
rswag#380

This PR adds some basic support for examples. It doesn't provide validation of examples. This is meant to be an initial implementation that we can add additional functionality to later if we need it.

With this change we now have the ability to call

request_body_example value: body

within the body of an rspec test in order to bind an example to the request.

You can also bind multiple examples by calling request_body_example multiple times

request_body_example value: body1, summary: "The basic example"
request_body_example value: body2, summary: "The fancy example"
request_body_example value: body3, summary: "The really fancy example" 

The summary is what appears in the dropdown seen in the image below.

By default, the summary is the summary defined by the rpec test when defining the method:
Eg, for

  path "/v2/catalog_outsource/workflows/{workflow_name}/vendor_tasks/{vendor_task_uuid}/error" do
    post "Error a vendor task" do
      tags "CatalogOutsource"
      operationId "ErrorVendorTask"
      consumes "application/json"
      produces "application/json"
     ...

The summary would be Error a vendor task

Lastly - this PR only supports static "values". Eg, you cannot reference a let (:body) { ... } it must be body = {}.
This is because I want to reduce the confusion if someone starts modifying the body object in nested contexts and ends up with a. bunch of "examples" that all have the same summary but different values.

[imran-iq]

I do not think this is needed as rswag /should/ already work with examples see:

we're not doing the above in the connect code base at the moment, but it should work

[kriston-costa]

Chatted with @imran-iq offline and he clarified that we'd like to move away from swagger docs anyway. Rather than adding support here we can revisit adding support to the connect DSL in the future.

Since other example support was already delivered I'm going to close this PR.

[Mtihc]

Quote:

I do not think this is needed as rswag /should/ already work with examples see:

we're not doing the above in the connect code base at the moment, but it should work

@imran-iq

The above does not give the desired result. It doesn't give you the nice dropdown.

You're defining the examples inside the schema. This results in the following swagger yml.

requestBody:
  content:
    application/json:
      schema:
        examples:
          Access token:
            client_id: 'blah etc'

where examples is nested under schema. But that's not what you want. You want examples to be a sibling of schema.

See chapter Request Body Examples here: https://swagger.io/docs/specification/describing-request-body/

In other words, this is what you want

requestBody:
  content:
    application/json:
      examples:
        Access token:
          value:
            client_id: 'blah etc'
      schema:

where examples is a sibling of schema. (side-note: also notice the extra value key)

That does give you the nice dropdown.

As far as I know there NO WAY to achieve this using rswag at the moment.