Are you open to maintaining a changelog, which I think is helpful especially with 0.y.z library versions to keep track of compatible vs. breaking changes.

Somewhat related to this, are you open to more frequent releases, so changes become available shortly afterwards?

The same applies to python-oas.

I've also contributed to mobx-keystone, which is a relatively young but nicely progressing project. I came to appreciate the changelog and frequent releases there and take it as inspiration elsewhere. What do you think?

Currently, only a single set of routes is generated based on the base path (the URL path of the first array element in the servers property of the OpenAPI spec) and the paths specified in the OpenAPI spec. I think it would be more consistent with the OpenAPI spec if routes for all array elements of the servers property were generated. If the servers property does not exist, then the base path falls back to / (same as now).

Taking this a bit further, I think also the scheme and hostname of the OpenAPI server object should be considered by the router when resolving routes, but I think Falcon currently doesn't support host-based routing.

What do you think @grktsh?

Same as #3, just for enum.

I believe OpenAPI supports nullable also for array items. falcon-oas currently does not honor nullable inside array items:

type: array
items:
  nullable: true
  ...

To support this, another custom validator for items needs to be added like this one:

I'd be happy to create a PR if you agree that array items can be nullable according to OpenAPI 3.

Hi,

First of all, thanks for this very promising OpenAPI middleware for Falcon!

I've noticed that a missing/empty request body, i.e. no JSON object at all, passes request body validation although the OpenAPI spec has a schema with required fields. When setting an invalid request body, e.g. an empty JSON object {}, validation fails and returns "Unmarshal Error" (400) as expected.

Currently, it is only possible to specify an access control handler via the x-falcon-oas-implementation property in the OpenAPI specification. Then, the access control handler is dynamically imported when the OAS middleware is instantiated.

This pattern makes an access control handler not configurable, e.g. providing credentials for a database with user credentials is only possible using global variables and/or environment variables, which is a bad design pattern. Instead, it should be possible to provide an access control handler to the OAS middleware class, e.g.:

mw = Middleware(..., security_handlers={'api_key': <handler function>, ...})

The new security_handlers argument could be optional and its value (dict) could be merged with the parsed handlers from the OpenAPI specification to continue support for the x-falcon-oas-implementation property and make the change backwards compatible. Perhaps the schemes provided in the argument could take precedence over the ones specified in the OpenAPI specification or an exception is raised when the same security scheme is specified in both places.

Since the Middleware class is typically not manually instantiated, the OAS class constructor should provide this argument as well and pass it through to the Middleware instantiation:

api = OAS(..., security_handlers={'api_key': <handler function>, ...}).create_api()

There is a similar problem with using x-falcon-oas-implementation for specifying request handlers, but it is solved by omitting x-falcon-oas-implementation in the endpoint specifications of the OpenAPI specification file and instead creating the router manually, which allows to instantiate resource classes manually and inject dependencies as needed.

I know that using a custom property lke x-falcon-oas-implementation or operationId for linking an endpoint to a request handler is quite popular (e.g. Connexion uses it too), but it facilitates bad design like using global/environment variables for configuration instead of dependency injection.

falcon-oas is for the most part a general OpenAPI validation library with a Falcon integration. Would you be open to factoring out the general OpenAPI validation core into an independent library? This way, other web frameworks like Flask can leverage this common core library, too. In my opinion, the community should agree on a common OpenAPI core library and add thin integrations with the different web frameworks leveraging the common core library instead of writing an extension specific to a particular web framework that includes the core logic all over again.

Some context:

I've been trying out several OpenAPI libraries including falcon-oas over the past year or so and noticed that efforts are scattered across the different libraries (with varying quality) although they should all be sharing a common core. I think you've done a terrific job in creating a solid validation core library leveraging jsonschema which is a proven JSON schema library. Not all OpenAPI validation libraries use jsonschema, e.g. openapi-core. Some do but don't support OpenAPI 3, e.g. bravado-core, or tightly couple the validation core with a particular web framework, e.g. connexion. falguard is quite similar to falcon-oas but builds upon bravado-core which doesn't seem to get OpenAPI 3 support anytime soon. Also, most OpenAPI libraries only report the first validation error whereas falcon-oas reports all, which I personally prefer. And then there are libraries that generate OpenAPI specs from inline annotations like flask-restplus, quart-openapi, flasgger etc., all of which implement the OpenAPI core logic all over again. This repeated core logic implementation also leads to slow adoption of OpenAPI 3 because each library needs to make the necessary changes.