ahx / openapi_parameters

openapi_parameters

openapi_parameters is an an OpenAPI aware parameter parser.

openapi_parameters unpacks HTTP/Rack query / path / header / cookie parameters exactly as described in an OpenAPI definition. It supports style, explode and schema definitions according to OpenAPI 3.1 (or 3.0). The gem is mainly build to be used inside of other OpenAPI tooling like openapi_first.

Learn about parameters in OpenAPI.

Synopsis

Note that OpenAPI supportes parameter definition on path and operation objects. Parameter definitions must use strings as keys.

Unpack query/path/header/cookie parameters from HTTP requests according to their OpenAPI definition

query_parameters = OpenapiParameters::Query.new([{
  'name' => 'ids',
  'required' => true,
  'in' => 'query', # Note that we only pass query parameters here
  'schema' => {
    'type' => 'array',
    'items' => {
      'type' => 'integer'
    }
  }
}])
query_string = env['QUERY_STRING'] # => 'ids=1&ids=2'
query_parameters.unpack(query_string) # => { 'ids' => [1, 2] }
query_parameters.unpack(query_string, convert: false) # => { 'ids' => ['1', '2'] }

path_parameters = OpenapiParameters::Path.new(parameters)
route_params = env['route.params'] # This depends on the webframework you are using
path_parameters.unpack(route_params) # => { 'ids' => [1, 2, 3] }

header_parameters = OpenapiParameters::Header.new(parameters)
header_parameters.unpack_env(env)

cookie_parameters = OpenapiParameters::Cookie.new(parameters)
cookie_string = env['HTTP_COOKIE'] # => "ids=3"
cookie_parameters.unpack(cookie_string) # => { 'ids' => [3] }

Note that this library does not validate the parameter value against it's JSON Schema.

Inspect parameter definition

parameter = OpenapiParameters::Parameter.new({
  'name' => 'ids',
  'required' => true,
  'in' => 'query', # or 'path', 'header', 'cookie'
  'schema' => {
    'type' => 'array',
    'items' => {
      'type' => 'integer'
    }
  }
})
parameter.name # => 'ids'
parameter.required? # => true
parameter.in # => 'query'
parameter.location # => 'query' (alias for in)
parameter.schema # => { 'type' => 'array', 'items' => { 'type' => 'integer' } }
parameter.type # => 'array'
parameter.deprecated? # => false
parameter.media_type # => nil
parameter.allow_reserved? # => false
# etc.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add openapi_parameters

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install openapi_parameters

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ahx/openapi_parameters.

openapi_parameters's Issues

Zeitwerk load issue with Rails (via openapi_first)

Hey! I like how this gem has been split out. Version 1 of openapi_first looks fantastic!

When the eager_load config is enabled:

Rails.application.configure do
  config.eager_load = true
end

I'm seeing the following error coming from Zeitwerk. I assume it's seeing the lib/openapi_parameters/errors.rb file and assuming there will be an Errors name.

$ bin/rails zeitwerk:check
Hold on, I am eager loading the application.
rails aborted!
NameError: uninitialized constant OpenapiParameters::Errors

I haven't played around with the Zeitwerk for_gem functionality at all so I'm not sure how it's meant to interact with Rails.

For now I've defined the class myself in an initializer.

Versions:

openapi_first (1.0.0.beta3)
  hanami-router (~> 2.0.0)
  json_refs (~> 0.1, >= 0.1.7)
  json_schemer (~> 0.2.16)
  multi_json (~> 1.14)
  openapi_parameters (~> 0.2)
  rack (>= 2.2, < 4.0)
openapi_parameters (0.2.2)
  rack (>= 2.2)
  zeitwerk (~> 2.6)

Happy to implement a fix for this, not sure what you'd like to do though. Cheers!