Add usage of feature #345 to README

[kaorukobo]

@ahx I wrote the FAQ section for #345. Could you take a look?

BTW I cannot find the tool to update the <!-- TOC --> portion automatically. (gh-md-toc was close but a bit different.) What tool do you use?

[ahx]

Thanks for the work. I would like to release a new version without the updated README to get a bit more time to think about where to put this.

[ahx]

Hey @kaorukobo

I think the feature you implemented in #345 to modify the path could be helpful to several users and I would like to make it usable without the need to add a custom middleware. So I am thinking about adding a "path" option which could be used like this:

spec = OpenapiFirst.load('openapi.yaml') do |config|
  config.path = ->(request) { '/api' + request.path }
end
use OpenapiFirst::Middlewares::RequestValidation, spec

or this

use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', path: ->(request) { '/api' + request.path }

Do you have any thoughts about that?

[kaorukobo]

@ahx I think this is a good idea. The former one would be better as we don't need add the same option to both RequestValidation and ResponseValidation which helps keeping the code under middlewares/ DRY.

In this approach, how can we exclude the paths which are not managed by the schema from validation? We would need an another option like this:

spec = OpenapiFirst.load('openapi.yaml') do |config|
  config.path = ->(request) { '/api' + request.path }
  config.only = ->(request) { %r'^/api' =~ request.path }
end
use OpenapiFirst::Middlewares::RequestValidation, spec

[kaorukobo]

@ahx That lambda returns the value like /api/api/resource. Shouldn't it be this?

  config.path = ->(request) { request.path.sub(%r'^/api', '') }

[ahx]

how can we exclude the paths which are not managed by the schema from validation?

This is a question that keeps coming up. One option is of course the one you described with sub-classing the Middlewares. This should still just work. I think having an option for that would be useful, especially for beginners. Let's make this discussion more transparent and create a dedicated issue about this.

[kaorukobo]

Let's make this discussion more transparent and create a dedicated issue about this.

@ahx Sounds good. I'll close this PR then and we can continue the discussion in a dedicated issue.