Customizations via metadata

[blocknotes]

Nice gem!

Can I propose you a small PR to allow more customizations via RSpec metadata?

Combined with the configuration:
RSpec::OpenAPI.description_builder = -> (example) { example.metadata[:openapi_description] || example.description }

A usage example could be:

  describe 'GET /api/v1/posts', {
    openapi_summary: 'list all posts',
    openapi_description: 'list all posts ordered by pub_date',
    openapi_tags: %w[v1 posts],
  } do
    # ...
  end

If you like the idea, I could update the specs and the README.

[k0kubun]

Using metadata for the purpose sensible to me. Please do update the specs and update README to document it.

How about overloading openapi: option and nesting keys under that though? i.e.

  describe 'GET /api/v1/posts', openapi: {
    summary: 'list all posts',
    description: 'list all posts ordered by pub_date',
    tags: %w[v1 posts],
  } do
    # ...
  end

When the option is taking a Hash, it's clear that it doesn't need to be openapi: false, so I think it doesn't conflict.

[blocknotes]

How about overloading openapi: option and nesting keys under that though? i.e.

Sounds good to me.
I was thinking the same at the beginning but I didn't want to replace your current behaviour.

About description - do you think that I could also add a customization there? Or it's better to avoid overriding the RSpec::OpenAPI.description_builder configuration method?

So this line: https://github.com/k0kubun/rspec-openapi/blob/master/lib/rspec/openapi/record_builder.rb#L53
Could become:

description: example.metadata.dig(:openapi, :description) || RSpec::OpenAPI.description_builder.call(example),

[blocknotes]

On second thought, I think that it could be good to let override also the description.
So I proceeded in that way.

[k0kubun]

👍