Add custom spec description option to run_test!

[mattpolito]

Problem

Specifications generated by run_test! are essentially a hard coded string of "returns a RESPONSE_CODE response". If you need to customize this you have to break down into the individual parts that run_test! constructs for us.

it "custom specification description here" do |example|
  submit_request(example.metadata)
  assert_response_matches_metadata(example.metadata)
end

Solution

To facilitate configuration without the need to break out of the nicety that run_test! provides, we can now pass a description as the first argument.

run_test!("custom specification description here")

A huge benefit to this is that when paired with auto generation of request/response examples, many example scenarios can be provided for documentation within the same response grouping.

NOTE: description is not an allowable option to pass down to a specification, so we delete it vs forwarding down to it.

The changes I made are compatible with:

• OAS2
• OAS3
• OAS3.1

Checklist

• Added tests
• Changelog updated
• Added documentation to README.md
• Added example of using the enhancement into test-app

[mattpolito]

@romanblanco If rswag is in need of maintainer help. We can be of assistance.

[a-lavis]

This is a great idea! I have a proposal of how we could do it slightly differently here: hashrocket#1
Let me know your thoughts!

[mattpolito]

Updated PR with test-app scenario

[BookOfGreg]

Hi @mattpolito, Roman pointed out your PR here on this project and I've chosen to grant you Write access to the project.
We hope you and the rest of the team at Hashrocket a good time with rswag.

[mattpolito]

@romanblanco now that you cut a release for 2.9.0, this is technically a breaking change. I was hoping it would make it in prior to the 'run_test!' options change. How would you like to handle this?

[romanblanco]

@mattpolito, my plan is to review and release this and other PRs in 2.10.0 before merging #574 and other future changes for 3.0.0.

I've tried to rebase your changes and run tests and everything is still passing.

[mattpolito]

@romanblanco It's not a breaking change in code but in usage. However after thinking about how ruby would handle the args vs options, I believe it will be fine after-all.

[romanblanco]

LGTM 👍

@mattpolito, @a-lavis, @ayunker, thanks for getting this done!