feat: Add documentation to schema

[duncanbeevers]

👑 Inline Documentation

This is a stab at what it might be like solving #128 (Inline Documentation)

I only attempted this using a small 3.0.2 schema and the Markdown documentation from OpenAPI-Specification 3.0.0.

The tooltips only match the abstract OpenAPI definition schema, and Markdown is rendered poorly.

• Scan documentation markdown for sections corresponding to the entries in the OpenAPI schema's definitions
• Add description fields for schema definitions from scanned documentation
• Add description fields the properties of simple definitions

Screen.Recording.2023-07-07.at.11.11.38.PM.mov

There are lots of brittle pieces here, and the markdown-in-tooltip is not ideal, but maybe this is a way we can provide a nicer developer experience without needing buy-in from OAI.

[CLAassistant]

All committers have signed the CLA.

[ak1394]

Thanks for the PR, it's very much appreciated! I'll update the PR once we reviewed it.

[duncanbeevers]

I chatted with the OpenAPI TDC today about the role of documentation in the JSONSchema document.

There were no concrete outcomes to this discussion, but the group seemed generally receptive to bringing the Markdown-based Spec document, and the JSONSchema document into closer agreement.

Historically, while the Markdown document has remained "frozen", the JSONSchema document derived from that Spec has been free to change to better-match that Spec. This implies that adding inline documentation to the schema should be possible, even for legacy versions of the Spec.