Configure routes from an OpenAPI definition

[smizell]

Request: add functionality that can configure routes in a Rails or Sinatra app.

This gem covers some really important areas to make it possible to go API-first in a Rack-based app. In order to go API-first, you need tooling that makes sure the API implementation matches the API design. This can be done at development-time, build-time, or run-time. A common place to mess this is up is with URLs and methods, though. People often manually configure the API routes in their application and then call APIs directly in their tests using URLs and methods.

What if there was a way for this gem to take an OpenAPI definition and build the routes for you in Rails or Sinatra? There are of course challenges to this as operations don't always align with how the API is implemented (e.g. an operation may not directly tie to a specific Rails controller). There may be some ways around this, such as OpenAPI Extensions.

Additionally, to fully remove the URLs and methods, you need to have a test client that can call the API based on the operation ID. That might be another feature beyond functionality to configure routes, but it could be one that's helpful.

If you have interest in this, I'd be happy to help explore this. We've done this for a Sinatra app and could apply what we've learned here. We could break it up into smaller pieces like that—Rails conf, Sinatra config, maybe a test client.

[ahx]

Hey @smizell

thanks for the issue. These are interesting ideas. I would first like to share a comment from another issue which should be relevant for this issue: #350 (comment)
One idea mentioned here is to not define routes in your rack framework at all, but call (custom or framework specific) actions/controllers from openapi_first directly. I did this based on the operationId, but you could use the path/method as well.
This would work around the whole routing part of specific frameworks, but we have to do that in part anyways because of the way we have to parse query parameters. One downside of this is that you loose the inspection features of a framework (rake routes). I don’t care about that too much, but in order to integrate with existing frameworks this would be crucial.

But your idea is not about that, but to have framework specific integrations where we tell openapi_first to “draw the routes for this OAD on that rails app” (or Sinatra, or Hanami etc.), right?

I cannot go into more details right now, but let’s keep the dialogue going.

I would be interested in how your approach with Sinatra looked from a user perspective. Can you share some code examples? Cheers, Andreas

[smizell]

We did something like this for Sinatra:

# Our Resource class implements all the features to build up the methods
# based on the URL and method
class MyResource < Resource
  # This was configured at the app level, but including here for completeness
  openapi_definition "openapi.yml"
  
  # This would match URL and method for us
  operation :my_operation_id do
    # handle request here
  end
end

Then in the tests, we'd have a client that did something similar.

test_client.my_operation(query_param: "value").call

All of this ensures that our implementation matches the URLs and methods in our OpenAPI file.

[ahx]

Thanks for sharing. We did something similar, where we had operaionIds like my_resource#index and some glue code that called MyApi::MyResource::Index.new(env).call(params).

What I like about this approach is that you don't have to repeat URLs outside of the API description. For testing we still use URLs and methods though (testing via rack-test), but that of course comes up with all problems that integration tests have like the need to satisfy all upstream authentication logic or the like where all you really want is to test this one handler/controller.

I am converting this to a discussion.