How strict should the OAS parsing be? #143
-
|
I was attempting to create a client for the Metabase API, but it turns out (despite them saying it is OAS 3.1.0) their spec does not 100% follow OAS. I created an issue on their github metabase/metabase#67748 Many projects do not follow the spec 100%. Yes, this is the fault of the project/underlying lib that is generating the spec, but unfortunately that is the reality of the current OAS ecosystem. Your https://github.com/phalt/cicerone package is doing the OAS parsing, so the compliance logic is separated somewhat, but the OAS compliance will still affect this project (if it is really broken and defaults in cicerone can't fix it). I know this is probably way too early in the project lifecycle to answer this, but I wanted to put it up here so we have a clear discussion. |
Beta Was this translation helpful? Give feedback.
Replies: 1 comment 2 replies
-
|
Cicerone was made separate for this exact reason - the problem with OAS parsers and spec generators is the quality of them is fuzzy, and I want to focus support on one small slice. I went pretty deep in the rabbit hole of this problem when I initially started Clientele because supporting them all felt very daunting. I personally would like to start by committing to 100% compliance with something - currently my thinking is the popular python web servers that I've already mentioned. Then based on the appetite in this exact discussion I'd like to increase coverage as we go. (That bug you linked is really unfortunate - 200 errors in a spec! But it shows how wide the quality window is of specs out there). |
Beta Was this translation helpful? Give feedback.
-
|
That makes sense. Maybe a target could be supporting 100% of 3.1.x + 3.0.x (FastAPI supports both?), + FastAPI, drf-spectacular, and Django Ninja. That would be MILES better than anything else. After that, collecting trivial OAS nonconformity issues (missing version) and handling those. I don't think it would ever make sense to handle major OAS spec misses. For instance, some Metabase issues are missing refs. You can't/shouldn't support that. |
Beta Was this translation helpful? Give feedback.
-
|
Yes, I agree and I am comfortable enough to say that is the goal. I think we're 99% there already and we need more real life testing to iron out the bugs - a bit like you have been doing :) |
Beta Was this translation helpful? Give feedback.
That makes sense. Maybe a target could be supporting 100% of 3.1.x + 3.0.x (FastAPI supports both?), + FastAPI, drf-spectacular, and Django Ninja. That would be MILES better than anything else.
After that, collecting trivial OAS nonconformity issues (missing version) and handling those. I don't think it would ever make sense to handle major OAS spec misses. For instance, some Metabase issues are missing refs. You can't/shouldn't support that.