-
Notifications
You must be signed in to change notification settings - Fork 6
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document that OpenAPI 2.0 is supported #9
Comments
Oh. Didn't know that 😃 Well, support for 2.0 is not tested or really even considered, so I would be inclined to document that it MAY support 2.0 but is not tested. Unless, of course, the 2.0 specification of Schema Object is identical (or a subset). I'm not that familiar with the older versions. |
The differences are as follow:
So the only things that matter here are:
|
Thanks for the differences, really helpful! So it should work otherwise except for the It's probably for the best to mention that it SHOULD work with 2.0 as well as long as there isn't |
I think the correct behavior for When it comes to So the correct behavior could be either:
Do you think it would be possible so that this library can be used for OpenAPI 2.0 as well? |
If you wanted to go ahead with the second idea (guessing the |
Basically all examples that define a file response have a schema object like this: schema:
type: file This doesn't even try to represent any JSON kind of thing, but rather some other file, so I don't see a point trying to convert it at all. I think the correct way to handle this would be to throw an exception to point out that one is basically trying to convert a file to JSON schema. Deleting the I would be interested to see cases where the type could be converted to something else based on other data in the And btw, sorry for the huge delay. I'm not working for the company anymore that triggered the development of this package. But I will now continue developing it on my free time more actively. |
I think there might still be some value to try to convert it. Specifically when OpenAPI is used not only to document an API but also to validate requests. I.e. schemas are converted from OpenAPI to JSON schema v4 then validated against incoming requests. In that use case, it would be odd to allow validating any request except the ones with
|
I can see your point and it certainly would make sense for requests. But the problem is that |
While it is technically not on the
I think the first two cases are the most common use cases of JSON schemas though, so maybe this would be useful to support this extension? An alternative solution would be to implement this but feature flag it behind an option? |
I think the first step is to support OpenAPI 2.0 so that any
Since the Let me know what you think. |
I would personally take it from this angle: in OpenAPI 2.0, request parameters, request body, response body and response headers can be described using a slight variation of JSON schema v4. For some reasons, the designers of the specification decided to use 3 different shapes for those JSON schemas depending on where it's used:
This is arguably confusing and that's probably why they corrected it in OpenAPI 3.0 where there is only one JSON schema definition. However many users might still want to take a request parameter or a response header and extract the JSON schema from it. That seems like a very legitimate thing users might want to do, regardless of the OpenAPI 2.0 design decisions above. It turns out supporting OpenAPI 2.0 request parameters and response headers might not require much work since the only changes are:
What do you think? |
This certainly makes sense and I understand your point now. The discussion and requested feature set has moved quite a bit away from the title of this issue which confused me a bit :) I suggest that we close this issue and not document at this point that OpenAPI 2.0 is supported, but rather create a new issue to actually (semantically) support OpenAPI 2.0 with its different schema shapes. Be free to create the new issue if you feel like doing so. You seem to have a firm grasp of OpenAPI 2.0. |
Thanks for the issues! It's probably better to leave this open although it might trick someone to believe that OpenAPI 2.0 is supported and not just documented. What comes to roadmap, do you have (or know someone who has) a need for OpenAPI 2.0 support? I was thinking about implementing a more complete support for OpenAPI 3.0 including support for |
I also think that OpenAPI 3.0 is the future and people will eventually leave OpenAPI 2.0. I would also personally love to just skip supporting it in my own projects 😃 Nevertheless I see two main reasons for supporting OpenAPI 2.0:
|
I agree and I was just thinking about the priority of "completing" OpenAPI 3.0 support vs adding OpenAPI 2.0 support. There might be flags that are relevant for OA 3.0, but not for OA 2.0 and vice versa. We might need to change the API a bit to support OA 2.0 while avoiding a flag mess. So in that sense I feel that OA 3.0 support should probably see some improvement before focusing on OA 2.0. |
Except for Based on this, I think OpenAPI 2.0 and OpenAPI 3.0 could both be supported without neither requiring the user to choose with an option/flag nor introducing branching logic in the code. Consequently I do not think there is any work as well when it comes to flags that are only relevant for one version, because they would not break anything if a schema from the other OpenAPI version was passed. When it comes to the work required, it seems like if #20 gets resolved, OpenAPI 2.0 will perfectly work. I don't think there is any other work to be done/prioritize to support OpenAPI 2.0, unless you see something else? |
Resolving #20 would require looking outside of I was revisiting #8 and thought that if we support |
Yes that makes sense! I created #19 for that purpose, maybe we should start working on that issue first? |
#19 discusses more about OpenAPI 2.0, so I suggest that we create a new issue for OpenAPI 3.0 parameter object support and then start looking at #19 and finally #20. It was a good idea you suggested in #8 when it comes to handling parameter objects. I'm a bit short of free time this week, so in the mean time go ahead and create the issue if you want. |
Just to make sure I understand what you mean: you mean converting an OpenAPI 3.0 Parameter object into a JSON schema v4? If so it might be a little tricky as OpenAPI 3.0 parameters can specify several JSON schemas (one per MIME type). |
Yes, that's what I mean. You mean multiple schemas with I think we could return an object where MIME types are the keys and and schemas the values. We convert each schema definition in Do you think that would work? |
I added #23 for continuation of this discussion. Follow up questions are: should we allow converting the following objects?
|
* fix: use clone instead of JSON * add test
This package actually also support OpenAPI 2.0.
Most of the OpenAPI ecosystem is (unfortunately) still stuck on 2.0 version, so documenting the fact this library supports it might be a good idea?
The text was updated successfully, but these errors were encountered: