Skip non API routes

[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.

Follow-up of #347 (comment) and #228

[kaorukobo]

@ahx Thanks for opening the dedicated issue. These days I could not take time to participate in discussions on these issues.

Now we have the new path option as of 2.7.0. If this option allows the passed lambda to return a value like OpenapiFirst::SKIP or nil, we can implement this without a custom middleware or a new option.

Like this:

oad = OpenapiFirst.load('openapi.yaml') do |config|
  config.path = ->(req) { 
    # /api/resource   => matches `/resource` in schema
    # /non_api_route  => skips validation
    m = request.path.match(%r'^/api(.*)')
    m[1] || OpenapiFirst::SKIP
  }
end
use OpenapiFirst::Middlewares::RequestValidation, oad

Do you like this idea?

[ahx]

Hey

I was thinking about some kind of skip: ->(reg) { true } option, but this sounds interesting as well! Can you explain why using the path option might be better?

[kaorukobo]

I was thinking about some kind of skip: ->(reg) { true } option, but this sounds interesting as well! Can you explain why using the path option might be better?

@ahx I think adding some kind of skip option is good, as it is very straightfoward for users.

One reason why I shared the above idea is that I will have to write as follows in my usecase, where (1) I want to serve both APIs on /api and pages on other paths in a single application, and (2) the paths in my schema does not start with /api:

oad = OpenapiFirst.load('openapi.yaml') do |config|
  config.path = ->(req) { request.path.delete_prefix('/api') }
  config.skip = ->(req) { !request.path.start_with?('/api') }
end
use OpenapiFirst::Middlewares::RequestValidation, oad

At first, this felt a bit non-DRY and verbose to me... but it rather looks simpler. Also I think there are few users who need to deal with the above (1) and (2) at once like my usecase.

Yeah. Now I think adding some kind of skip: ->(req) { true_to_skip } or only: ->(req) { false_to_skip } is very good approach.

I prefer only as I can remove ! from the above snippet.

[ahx]

Hey @kaorukobo. Thanks for the input. Another thing I am thinking about is having an option on the request validation middleware to skip unknown requests. Something like

use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', ignore_unknown_paths: true

This would change the behavior to not return a 404 if the request path is not defined in 'openapi.yaml', but just pass it to the next middleware or app in the rack stack, which would probably return a 404 itself. I can see one problem with this: The request path would still go through openapi_first's router to see if it can find a match. What do you think? Should this even become the default behavior (in the next major release)?

[kaorukobo]

@ahx Yeah, we might not need to have an option like skip. If there were no performance concern, as I'll mention later, I think it would be good to just bypass incoming paths that are not defined in the schema as a fixed behavior. I cannot think of use cases where we would need ignore_unknown_paths: false, where we have controllers bound to paths not defined in the schema but still want to prevent them from responding (like /api/hidden_route.)

I can see one problem with this: The request path would still go through openapi_first's router to see if it can find a match. What do you think?

Yes. I'm concerned about the overhead of the router processing any unrelated requests as it has to parse path parameters.

We might still need an option like skip or only. With such options, the current behavior (returning 404 if the request path is not defined) makes sense because users will not continue to use the library without being aware of the hidden overhead.

[ahx]

One of the main goals for openapi_first is to avoid API drift. So the intention behind the current behavior (return 404 for unknown paths) was to force users to describe all API endpoints as unknown endpoints will always result in a 404. Thanks for your input on this. Will have to think about that some more…

One other thing I had in mind for a while is to somehow use the router of the upstream app's rack framework instead of running through our own router first AND the app's router afterwards. That would require some framework specific integration, though. Another way to get rid of the overhead is to build a framework on top of openapi_first and just use openapi_first's router to call your application code (here is an example).

Will have to think about theignore_unknown_paths option and/or the skip some more later. Thanks again for the input.

[gobijan]

Hi, I just had a look how I solved it for Sunnybox and I went with this:

module OpenapiFirstEnabler
  extend ActiveSupport::Concern

  included do
    if Rails.env.test?
      use OpenapiFirst::Middlewares::ResponseValidation,
        spec: Rails.root.join("public", "api", "v1", "openapi.yml"),
        raise_error: true
    end

    use OpenapiFirst::Middlewares::RequestValidation,
      spec: Rails.root.join("public", "api", "v1", "openapi.yml"),
      error_response: :jsonapi,
      raise_error: false # Rails.env.test?
  end
end

And this concern is then included in my API controllers:

class Api::BaseController < ApiController
  include OpenapiFirstEnabler
  ...
end

Does this make sense for you guys?