restish
restish copied to clipboard
danielgtaylor
OpenAPI v3.1 Support
Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.
I saw this, and I am going to guess it means 3.0 only:
In general, OpenAPI 3 just works with Restish. There are a couple of things you can do to make sure your users can more easily use Restish with your API.
OpenAPI v3.1 has a bunch of great little changes, solving problems like the the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.
Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.
- https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
- https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
- https://nordicapis.com/whats-new-in-openapi-3-1-0/
Here are some example files which can make for handy pass/fail test cases:
https://github.com/Mermade/openapi3-examples/tree/master/3.1
If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:
https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1
No rush, but when you're starting work on it, please update this issue so I can update openapi.tools to reflect that, and folks will have a way to subscribe for updates.
LMK if you have any questions!
Hey @philsturgeon! OpenAPI 3.1 support is currently blocked on https://github.com/getkin/kin-openapi/issues/230, but since only a few things changed in a backward-incompatible way many OpenAPI 3.1 specs may already work with Resitsh today.
Hey @danielgtaylor, is https://github.com/sv-tools/openapi any help at all? or https://github.com/pb33f/libopenapi?
These look very interesting. I'll take a look soon and see how much effort it would be to switch and whether they have all the features I need. The good news is that in Restish it's mostly just read-only support and it's isolated to the openapi package which translates into a generic model for Restish itself to use. Because of this modular approach we could theoretically just use a new library for OpenAPI 3.1+ if I run into any back-compat issues. Just need to find some time!
@philsturgeon, @waldyrious, @tploss I've created a draft PR for OpenAPI 3.1 support, see https://github.com/danielgtaylor/restish/pull/145. It could use some testing before I make a new release.
Unfortunately I am not working with OpenAPI specs at the moment, so I'll have to leave the testing to others. But I just want to say I loved to see the interactions you had with @daveshanley on https://github.com/pb33f/libopenapi and how the library got progressively better with each change. Now that's open source at its best!
