flask-restx does not support Swagger/OpenAPI 3.0

[jkugler]

Describe the solution you'd like
Swagger/OpenAPI version 3.0 has been out since the middle of 2017 (https://swagger.io/specification/). The source code (https://github.com/python-restx/flask-restx/tree/master/flask_restx/schemas) indicates only 2.0 is supported, which was last updated in 2015, it seems. I would rather not start a new API project using the old Swagger/OpenAPI specification.

Is there any current work to support the version 3.0 schema?

[jblom]

@jkugler currently I'm also looking for a nice way to support OAS 3.0 using python. It seems however that support is not great yet.

As to flask-restx I don't think it will support 3.0 any time soon, since it is maintained by a couple of volunteers (still grateful for saving flask-restplus :-) ) and the change in spec is not trivial, making it quite the task to pull off (also mentioned here here)

Based on trying out https://editor.swagger.io/ to figure out the level of support for 3.0 as well as reading a bit here and there, my conclusion for now is to stick to OAS 2.0, using flask-restx until the support for 3.0 has improved (als our current infrastructure uses flask-restx, so I will only migrate if support is great).

You could still check out https://github.com/zalando/connexion but it seems a bit too bulky (at least for my taste). Also I am really fond of using the in-code annotations to generate the OAS spec, rather than vice-versa (i.e. use the spec to generate code).

[jkugler]

@jblom I agree. I'd much rather write up my code, and annotate. That is much clearer to me than writing a spec...and hoping I got my YAML correct. :)

[jblom]

@jkugler Also thinking now it might be handy to just use a convertor to generate a 3.0 spec from the swagger.json of flask-restx. That way you can load that thing into e.g. Postman or distribute to your clients or whatever

[twsl]

#26

[pmundt]

While investigating this issue, I stumbled upon https://github.com/marshmallow-code/apispec which also supports flask. It's not going to do much good for people who have already committed to flask-restplus/flask-restx, but could be an alternative for those wondering what to pick for new designs.

[jkugler]

@pmundt Thanks for the pointer. apispec suffers from the same drawback I saw on other API generators: you have to code up your API, and you have to then document the API in the doc string with YAML. The thing I like about restx is that there is no duplication. Your code generates your API. You're not doing double work to keep your Swagger generation up-to-date.

[MartijnGevaert]

Something small to add, I use JsonSchemas for validation, both $schema and anyOf are fields which now end up in the OpenApi 2.0 documentation, but are actually only supported by OpenApi 3.0. When using OpenApi generator to create an SDK based on the OpenAPI doc this throws a warning.

[Abdur-rahmaanJ]

The solution seems to be helping the project by becoming a maintainer

[j5awry]

closing as dupe of #26

I'm putting a reply in #26

[j5awry]

Also, you don't need to be a maintainer to help move things along. this is open source, and anyone can contribute, anyone can drop into PRs and give reviews. Maintainers are folks with merge and tagging rights. I try to keep Gitter open these days, so anyone can ping me there, and say "I've reviewed X, could you take a look as well to get it merged?" But we need to keep the list of maintainers generally small (as in the group with Github Maintainer rights).

I'll add some more notes in the maintainer issues