Request body examples

[romanblanco]

Problem

Closes #380

Solution

Cherry-picking @kriston-costa's solution from instacart#4

This concerns this parts of the Open API Specification:

• Request Body Examples

The changes I made are compatible with:

• OAS2
• OAS3
• OAS3.1

Related Issues

• Request examples #380
• https://github.com/instacart/rswag/pull/4/files

Checklist

• Added tests
• Changelog updated
• Added documentation to README.md

Steps to Test or Reproduce

# spec/integration/blogs_spec.rb
describe 'Blogs API' do
  path '/blogs/{blog_id}' do
    get 'Retrieves a blog' do
      request_example value: { some_field: 'Foo' }, name: 'request_example_1', summary: 'A request example'
      response 200, 'blog found' do
        ...

[kstevens715]

We need this exact feature. I tested this branch out in our project and it worked out great. For us, we wanted to be able to use the actual request from the spec as the example, so we did it in an after block. But I think what you have here is good enough for our use case. I'd love to see this get merged! Thanks for your work!

  config.after(:each, operation: true, use_as_request_example: true) do |spec|
    spec.metadata[:operation][:request_examples] ||= []

    example = {
      value: JSON.parse(request.body.string, symbolize_names: true),
      name: 'request_example_1',
      summary: 'A request example'
    }

    spec.metadata[:operation][:request_examples] << example
  end

[bblimke]

The method is request_body_example and not request_example so either README has wrong name or the method. Not sure what was the intention. request_body_example is probably more intuitive.

[romanblanco]

Thanks @bblimke, you're right!

#566

[harlantwood]

We need this exact feature. I tested this branch out in our project and it worked out great. For us, we wanted to be able to use the actual request from the spec as the example, so we did it in an after block. But I think what you have here is good enough for our use case. I'd love to see this get merged! Thanks for your work!

  config.after(:each, operation: true, use_as_request_example: true) do |spec|
    spec.metadata[:operation][:request_examples] ||= []

    example = {
      value: JSON.parse(request.body.string, symbolize_names: true),
      name: 'request_example_1',
      summary: 'A request example'
    }

    spec.metadata[:operation][:request_examples] << example
  end

This is awesome 😄
To spell it out a bit more for people who need it (like me):

1. put this in your swagger_helper.rb
2. tag the spec that you want to use as a request example with use_as_request_example, eg:

      response(200, "successful", use_as_request_example: true) do

[harlantwood]

Since this PR is merged but not yet in a gem release, I am using this feature by loading the gem from github with the following entry in my Gemfile:

  gem "rswag-specs", git: "https://github.com/rswag/rswag.git", branch: "master", 
    glob: "rswag-specs/rswag-specs.gemspec" # to get request examples, merged in https://github.com/rswag/rswag/pull/555

[BenKanouse]

For my project I edited the above example to look like this:

  config.after(:each, operation: true, use_as_request_example: true) do |spec|
    spec.metadata[:operation][:request_examples] ||= []

    example = {
      value: JSON.parse(request.body.string, symbolize_names: true),
      name: spec.metadata[:response][:description].parameterize.underscore,
      summary: spec.metadata[:response][:description]
    }

    spec.metadata[:operation][:request_examples] << example
  end

The main difference is that the name and summary of the example come from the spec's description. This means that you can have multiple response blocks use the use_as_request_example without them overwriting each-other and the name/summary in the ui looks a bit nicer than a static value.