How to handle non API routes?

[gobijan]

I am currently figuring out an easy way to make use of both validation middlewares in my test for an app that has api routes where the middlewares make sense and some normal oldschool rails routes that should be excluded.
What is the recommended way here?

I thought about disabling the middleware and build a helper to mark tests that should be openapi_first validated.
Another approach could be a middleware that checks if the path starts for example /api/ and only then loads the validation middlewares.

What do you recommend? How you handle this?

Currently I load in test.rb which makes normal controller tests fail of course (these routes should not be included in openapi.yml ofc):

config.middleware.use OpenapiFirst::Middlewares::ResponseValidation, spec: Rails.root.join('public', 'openapi.yml'), raise_error: true
config.middleware.use OpenapiFirst::Middlewares::RequestValidation, spec: Rails.root.join('public', 'openapi.yml'), raise_error: true

[ahx]

Hi Bijan,

If you have a shared controller for your API routes one way could be:

module Api
  class ApplicationController < ActionController::API
    if Rails.env.test?
      use OpenapiFirst::Middlewares::ResponseValidation,
          spec: Rails.root.join('public', 'openapi.yaml')
    end
    use OpenapiFirst::Middlewares::RequestValidation, spec: Rails.root.join('public', 'openapi.yaml'),
                                                      raise_error: Rails.env.test?

    # ...
    #
  end
end

What do you think about that variant?

Could you share why you don't use the request validation middleware in production? Are you concerned about performance?

I know that several people have the use case you described, so I am very open to add a more integrated solution to solve this.

[ahx]

Hi again, another option would be to subclass the build in middlewares like this:

class MyResponseValidation < OpenapiFirst::Middlewares::ResponseValidation
  def call(env)
    if Rack::Request.new(env).path == '/health'
      super    
    else
      @app.call(env)  
    end
  end
end

Or what do you think about an option to skip validation for certain requests (not implemented)?

  config.middleware.use OpenapiFirst::Middlewares::ResponseValidation,
    spec: 'api/openapi.yaml',
    except: ->(env) { env[Rack::PATH_INFO].start_with?('/assets') }

[gobijan]

Hi Andreas,
thanks for your input. These approaches kind of all make sense.
For now I think I'll try my luck with the controller extension variant.
Good point with the request validation. I guess you're right and I can try to turn it on by default.
Right now I am experimenting moving Sunnybox from Rswag to openapi_first in order to get rid of rspec rswag dsl.
I like your gem a lot as it supports openapi 3.1 and is a smart approach to ensure the spec doesn't get out of sync with the implementation.

[ahx]

One thing using the request validation middleware on production enables is accessing the parsed request parameters.

The middleware has to parse parameters and request body for validation and adds request.env[OpenapiFirst::REQUEST] to the Rack env. This is an instance of RuntimeRequest, which gives you access to the parsed request body and also parsed parameters. These are parsed exactly as defined in the OpenAPI spec. This enables using things like comma separated values in path parameters without the need to split and convert values, but also comes with some limitations. This can make Rails' Strong parameters obsolete, but does hinder people to use it.

If you happen to find the time and resources to test this out, any feedback would be appreciated.

[gobijan]

Yeah that sounds really good.
I'm currently migrating my tests. I think I'll be through with it today if no major road blockers occur.
First tests are already working out fine.
I'll let you know how it went for me.

[gobijan]

Hey Andreas,

I just finished removing rswag / rspec from my stack. Now my tests are running in 20s compared to more than a minute before.
This workflow works really nice for me and https://sunnybox.io will run on OpenAPI 3.1 as soon as I deploy.
Awesome.

My experience:

• One getting it setup was easy and documentation is good.
• I wrote a concern that is required in my API Base Controller including the middlewares (as suggested by you).
• While debugging some endpoint responses I had to deactivate the middlewares or change the raise_error in order to reach debugger in my test itself.
• I wrote a rake task that does a validation against https://validator.swagger.io to handle the final validation of my openapi document. This is not covered with the gem, isn't it?

Love this gem and will write a blogpost about it and spread the word <3

PS: I added 3000 LOCs and removed 5000 ☺️

[ahx]

Hi @gobijan

thanks for the feedback! I am happy to hear that this works for you! :)

While debugging some endpoint responses I had to deactivate the middlewares or change the raise_error in order to reach debugger in my test itself.

I usually use something like raise_error: Rails.env.test?, but I still sometimes had to change Rails' (or Sinatra's) default error handling configuration to figure out what's going on in tests. I don't like this and I wish we could find a useful default setup to use in tests or add some test / framework integration or maybe just adapt exception messages to make this workflow easier. But I am not sure how.

I wrote a rake task that does a validation against https://validator.swagger.io/ to handle the final validation of my openapi document. This is not covered with the gem, isn't it?

At work we are using redocly lint to vaildate the API and enforce some style guides. There is JSONSchema.openapi.validate and I think it could be useful to add a way to call that via openapi_first. I did not try JSONSchema.openapi.validate, yet but I think we would need to add some glue code to emit useful error messages.

Thanks for your input and contribution!

[gobijan]

Didn't know redocly lint but just used it and found a few things to optimize. Nice one :)

[ahx]

I have created an issue to validate the OpenAPI file so one can track the status of that feature there. I like the idea.

An API about skipping non-API routes while using the built-in middlewares globally is still up for debate.