ahx/openapi_first

Build your API on top of OpenAPI. Ensure that your implementation follows exactly your API description.

openapi_first's Issues

Add support for multiple content types

Would be nice to be able to have a single route take requests with either json and respond with json, or take requests with json-api and respond with json-api.
This would be really useful f.e. for the transition phase of moving an API endpoint from json to json-api

refs https://stackoverflow.com/a/46696137/1627888, go-swagger/go-swagger#1319

The purpose of hanami in this gem?

Hi there 👋🏻

We're considering using openapi_first in a Rails app - particularly given the support for OpenAPI v3.1 - but I'm wondering why hanami-router is a dependency for the validation process? To be clear: I'm a fan of hanami, and use it in other projects - it's just that I don't want to bring in a tonne of new indirect dependencies for such a focused need, and I don't immediately grok the purpose of it here. If you have the time to enlighten me, that'd be much appreciated :)

Don't read uploaded files to validate "binary" fields

tbd

Add option to find a custom handler

Sometimes you dont want to change the operationId so map the operation to a handler. The library should support that.

Some options:

• Use a x-handler field that overwrites the operationId field
• Use code to map one operationId to a certain handler

🤔

Support Security Scheme

We currently just ignore security schemes. Let's change that.

Support "discriminator" (OpenApi flavoured JSON Schema)

Idea: Return customizable Sunset header for deprecated endpoints

Sunset header

Manual response validation breaking change in 1.0.0->1.1.0 upgrade

Hi!

I just upgraded to 1.0.0 and then to 1.1.0. I am using the manual response validation (more or less) as follows:

# in my middleware
definition = OpenapiFirst.load(...)
response = @app.call(env)
definition.request(Rack::Request.new(env)).response(Rack::Response[*response]).validate!

My response validation breaks in 1.1.0 with NoMethodError: undefined method 'join' for #<ActionDispatch::Response::RackBody:... on @rack_response.body.join in OpenapiFirst::RuntimeRequest (here) because my @rack_response.body is a ActionDispatch::Response::RackBody.

In the rack repo I found that the body is usually expected to respond to each or call so maybe we could go back to using each? :)

Improve error message if value is not defined in enum

In the error {"errors":[{"source":{"pointer":"/data/type"},"title":"is not valid: \"my_type1\""}]} I have no clues which are the valid values, which would be nice to print in case of an enum so it's easier to find out what error one did when specifying the endpoint in the openapi.yaml

Convert `format: 'date'`, `format: 'date-time'` to Ruby objects

Let's parse 'date', 'date-time' and 'time' formats.

Convert 'date' to Date, 'date-time' to Time and 'time' to Time with 1970-01-01. Cool?

415 Unsupported Media Type when posting form data from Postman

Hi there @ahx ,

I have this spec:

paths:
  /api/v1/test:
    post:
      summary: test
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              properties:
                id:
                  type: string
                  format: uuid

And when I try to do a POST with form-data on Postman, I get

{
    "errors": [
        {
            "status": "415",
            "title": "Unsupported Media Type"
        }
    ]
}

Is is my Postman request body:

and headers:

Any idea why the response is unsupported Media Type?

thanks so much for this gem!

Manual request/response validation

The idea is to programatically validate requests/responses.

See also #169 (comment) #140.

Api proposal:

OpenapiFirst::RequestValidator.new('my/openapi.yaml')

request = Rack::Request.new(env)
validator.validate(request)  # Returns an object with details about the validation result (error?, schema, data, etc.)
validator.validate!(request) # Raises an exception if request is invalid

UPDATE: See Variant 1

Better content negotiation

If no matching reponse content type can be found for the requests accept handler, the middleware should response with 406. See prism/test-harness about testing content negotiation.

Add Path parameter validation

Invalid JSON not gracefully handled

When providing a post body with invalid JSON (i.e. a trailing ,), I get an error 500 with a stack trace in the response instead of well formatted JSON error response:

MultiJson::ParseError: expected array element, not an array close (data.attributes.queueIds) at line 7, column 8 [parse.c:554]
	/Users/thomas.fruetel/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/multi_json-1.14.1/lib/multi_json/adapters/oj.rb:34:in `load'
	/Users/thomas.fruetel/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/multi_json-1.14.1/lib/multi_json/adapters/oj.rb:34:in `load'
	/Users/thomas.fruetel/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/multi_json-1.14.1/lib/multi_json/adapter.rb:21:in `load'
	/Users/thomas.fruetel/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/multi_json-1.14.1/lib/multi_json.rb:122:in `load'
	/Users/thomas.fruetel/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/openapi_first-0.6.9/lib/openapi_first/request_validation.rb:47:in `parse_and_validate_request_body!'
...

Feel free to contact me on Slack/Discord if you need more detailed instructions to reproduce this.

Add Allow header to OPTIONS response

We could return allowed request methods when a client tries to identfy allowed request methods via an OPTIONS request. Is that a good idea?

Find handler methods during initialization

Currently handler functions are searched during each request, which is time consuming and not neccessary.

The plan:

• move the namespace option from OperationResolver to Router and let Router find the handler method during initialization
• replace OperationResolver with a very simple CallHandler class or the like

Spec has a binary field - openapi-first failing with exception trying to get the :tempfile

Field isn't in required so by default it is optional. Yet it's tried to be read.

data is the payload, property the name (image in my case) but it wasn't sent so data['image'] # nil

    def binary_format(data, property, property_schema, _parent)
      return unless property_schema.is_a?(Hash) && property_schema['format'] == 'binary'

      data[property] = data[property][:tempfile].read ### 
    end

Is anybody using the standalong mode (OpenapiFirst.app)

The standalone mode was mainly inspired by connexion. I like the approach, but I am wondering if others are using it. If not, I would like to remove that part in order to make the project easier to maintain.

Support OpenAPI 3.1

Including JSON Schema 2019-09

Request header validation

Note: "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored. - OAS spec

Response header validation

Payment required

🚨 You privatised your repo. 🚨

Hello!
You have set your repository to private. From now on Greenkeeper is no longer free. We have disabled your repo for now.
Please enter your payment information at account.greenkeeper.io.
For pricing information, please visit https://greenkeeper.io/#pricing.

Coercion of path and query string parameters

Currently these are not converted in any way, so they are always strings.

Add request body validation

See https://github.com/ivx/openapi_first#todo-request-body-validation

Add option to specify to find either "class" or "function" handler

You usually prefer either the "function" handler MyApi.my_action or the "class" handler MyApi::MyAction#call. You should be able to choose without modifying the OAS file.

Access operation level or top-level `security` object

OpenapiFirst::Definition::Operation#security should return information about the security scheme of the current operation and it's scopes/values. If no security scheme is defined for the operation, it should return the top-level security scheme if that is defined.

See specification: Operation, Security Scheme

Response validation middleware

Having a Rack middleware that does response validation (in development env) should be useful to help keeping implementation and API description even closer.

Add all request validation aspects into one middleware

use OpenapiFirst::RequestValidation

v1.0.0.beta5 release not available via rubygems.org

Hi :) I (and a couple of other people) have an issue with installing the newest version (beta5) from rubygems.
I know it's probably not a code-related issue (I tested the gem directly from the main branch and it works fine), but I couldn't find a better place to raise it.

# when using gem install
gem install openapi_first --pre --version "1.0.0.beta5"
ERROR:  Could not find a valid gem 'openapi_first' (= 1.0.0.beta5) in any repository
ERROR:  Possible alternatives: openapi_first

# when setting version in the Gemfile
Your bundle is locked to openapi_first (1.0.0.beta5) from rubygems repository https://rubygems.org/ or installed
locally, but that version can no longer be found in that source. That means the author of openapi_first (1.0.0.beta5)
has removed it. You'll need to update your bundle to a version other than openapi_first (1.0.0.beta5) that hasn't been
removed in order to install.

At the same time I can successfully download the gem from the rubygems https://rubygems.org/gems/openapi_first/versions/1.0.0.beta5 🤔

Allow to customize error responses (not JSON:API)

Performance benchmarks

Compare performance of this with a generic Sinatra, Rails, Hanami app that about the same request validation features.

Capture names affects finding definitions for nested routes

We had a surprising issue that lead us to hanami/router (see this issue: hanami/router#252) where defining routes with different capture names can lead to definitions not being found for nested paths.

Given the following paths:

/foo/{id}
/foo/{foo_id}/bar

The second route won't be found by the router. Luca suggested adding the /foo/{foo_id}/bar route first so it matches earlier.

I see a few options:

1. Do nothing, maybe document the behaviour in the README to tell people not to mix capture names
2. Order the paths intelligently before building the router
3. Warn while building the router if there are path conflicts

Any other ideas?

Overwork Coverage testing

While Using the coverage functionality of openapi first i found some problem. In general it is a good idea to use the test_helper base class with before all and after all. But from this class it get inhertated several times. So it is not really a before all tests. Small example:

class RouteTest < Minitest::Test
  include Minitest::Hooks

  before(:all) do
    spec = OpenapiFirst.load('./openapi/openapi.yaml')
    @app_wrapper = OpenapiFirst::Coverage.new(VacationApi::App, spec)
  end

  after(:all) do
    message = 'The following paths have not been' \
              "called yet: #{@app_wrapper.to_be_called}"
    assert_empty @app_wrapper.to_be_called, message
  end

  def app
    @app_wrapper
  end
end

And inherit in different classes:

class QuotaTest < RouteTest
   ...
end

class OtherTest < RoutTest
   ...
end

As you see the coverage test is executed for QuotaTest and OtherTest class. So Test fails because OtherTest covers not QuotaTest routes.

Cookie request parameter validation

Do we want it?

Make request validation usable without namespace/handler

Support "nullable" (OpenApi 3.0 only)

Currently OpenapiFirst does not support "nullable" of the OpenApi flavoured JSON Schema.

See davishmcclurg/json_schemer#22

Respect server.url ?

In an OAS server object you can use paths and even template strings. This should be taken into account by ´OperationidResolver` and when testing.

Support "explode" and "style" parameter arguments

Create code generator

1. Describe your API
2. Run a generator
3. Fill the gaps
   ✨

Feedback wanted 👋🏼

I am wondering if anyone is using this and what they like and dislike about this tool. I have some ideas what to change, but I'd like to hear from people outside. Feel free to create issues or reply here or write something in the chat.

Add RSpec matcher for response validation

See https://github.com/ivx/openapi_first#response-validation

Some inspiration: https://github.com/ketiko/open_api-rspec

Set a valid default content-type from API description

Currently you have to set the response's content-type by yourself. Let's change that so that OpenapiFirst sets the content-type if it is not set by the app. Let's just pick the first content-type in the API description for the the status code returned by the app.

Support application/problem+json for error responses

https://tools.ietf.org/html/rfc7807

Related to #39

What's the best way to validation request/responses without using the router (in Rails)?

Hey,

We're currently (slowly) adding OpenAPI for request/response validation to an existing Rails app. We can't easily switch all the way to adding operations and the router to replace our controllers but I'd like to introduce some middleware to log schema errors so we can build a dashboard to track exceptional cases.

I've had a bit of a poke through the validator and middlewares included in the app but they all seem to reference operations and expect the router to be in place. I'd really appreciate a nudge in the right direction as I'll probably be digging into the private API a bit.

Cheers!

Find a better name for `OperationResolver`

It sounds overly abstract, doesn't it?

Custom error messages for request validation

When defining for example a parameter that represents a hex color ("/#[0-9a-f]{6}/i") a generic message like "does not match pattern" is not helpful.
Also think about i18n and fallbacks.

Support readOnly and writeOnly keywords

You can use the readOnly and writeOnly keywords to mark specific properties as read-only or write-only. This is useful, for example, when GET returns more properties than used in POST – you can use the same schema in both GET and POST and mark the extra properties as readOnly. readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses.

• https://swagger.io/docs/specification/data-models/data-types/#readonly-writeonly

Related to davishmcclurg/json_schemer#55

Support nested parameters described as string like `name: 'fields[article]'`

Currently we support nested query parameters that are describes as type: object with a nested schema.
We should also support query parameters that are described as name: 'fields[article]' and type: string, which will be parsed by rack as a nested obect by default.

Support Rack array parameters like`name: 'fields[]'`?

Should we support name: 'fields[]' which gets parsed as an array?

Follow-up of #40