Prepare documentation additions for the 3.2 release #137
Conversation
Co-authored-by: Ralf Handl <[email protected]>
There was a problem hiding this comment.
@lornajane a few "take it or leave it" comments in here, but looks good 👍
| The root object in any OpenAPI Description is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), and only two of its fields are mandatory: `openapi` and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required. | ||
|
|
||
| * `openapi` (**string**): This indicates the version of the OAS this OAD is using, e.g. "3.1.0". Using this field tools can check that the description correctly adheres to the specification. | ||
| * `$self` (**string**, OpenAPI 3.2+): Provides the canonical URI for the document itself, used as the base URI for resolving relative references. This field is optional. |
There was a problem hiding this comment.
Another optional clarification but this one is more tenuous.
"used as the base URI for resolving relative references, and for humans understanding uniquely defined API descriptions".
|
|
||
| 1. **Use hierarchical organization** for complex APIs with many operations | ||
| 2. **Provide summary fields** for all tags to improve navigation clarity | ||
| 3. **Use consistent kind values** - follow registry conventions |
There was a problem hiding this comment.
Do you think is worth qualifying explicitly i.e. what the registry convention is right here
"- follow the conventions found in the Tag Kind Registry."
There was a problem hiding this comment.
Isn't that the point of the registry? I'm not sure I understand the change you're suggesting.
There was a problem hiding this comment.
I meant write this sentence: "Use consistent values - follow the conventions found in the Tag Kind Registry"
i.e. explicitly say "Tag Kind Registry" in the bullet, so it's clear and unequivocal, and uses the explicit name, for readability.
Co-authored-by: Karen Etheridge <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
5 participants
Rather than putting key information in the announcements, I've moved a lot of the content to here so that it can be linked to and evolved over time. Hopefully it's enough to get us started!