docs: adds an upgrade guide for overlay 1.1 #169
Conversation
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
Signed-off-by: Vincent Biret <vincentbiret@hotmail.com>
lornajane
left a comment
lornajane
left a comment
There was a problem hiding this comment.
Love having the upgrade guide ready already! Added some comments.
|
|
||
| Since the `in` keyword is undefined in the RFC. | ||
|
|
||
| ## Removing/Updating primitive values is now fully supported |
There was a problem hiding this comment.
When did we add this feature and do the tools support it?
There was a problem hiding this comment.
In this PR OAI/Overlay-Specification#225
And yes clio supports it, some others do
| overlay: 1.1.0 | ||
| ``` | ||
| ## Copy elements from the OpenAPI document |
There was a problem hiding this comment.
Let's not include the optional features in the upgrade guide. Signpost the docs by all means, but let's put the actual upgrading things in this document (or at least, make it clear that these are optional steps and put them later in the document). Many users will not need this feature but may want to upgrade.
There was a problem hiding this comment.
I believe the main appeal of upgrading is to use the copy feature. Yes we have additional minor improvements in this new version, and some required "technical upgrades" that I suspect will only impact very few users.
May I suggest dividing this document in two sections: the required upgrade steps, i.e. things won't works in 1.1 if you don't take these steps. And the optional steps, those are things you want to consider as you've upgraded to v1.1 (copy, info description, etc...)
There was a problem hiding this comment.
Actually, I just remember something. I used the upgrade guide for OpenAPI from v3.1 to v3.2 as an inspiration to write this one.
It's FULL of optional upgrades (like using the new query operation for instance) that people might want to consider and benefit from, but that are not strictly required to get a document compliant with the 3.2.0 spec.
So I'm not sure why this upgrade guide, which will "sit" right next to the OpenAPI one, should be any different in terms of content?
|
@lornajane I just merged that so we don't linger too long with a "broken link" in the GH release for Overlay. Happy to follow up with another PR if required later on once you've had time to review my responses. |
3 participants
No description provided.