Inline Documentation support

[Profpatsch]

It would be cool if the mode could display documentation of the fields when hovering over keys, or looking at intellisense completions.

[ak1394]

Hi @Profpatsch ! Are you talking about editing YAML files? Where it shows "Validation schema for OpenAPI ..."?

[Profpatsch]

Yes! Exactly. I’d expect some documentation about the field at that point.

[ak1394]

These text in these hovers comes from OpenAPI JSON schema we use for validation. Unfortunately, the official schema does not come with the "description" fields for every property defined in schema.

We'll look into adding descriptions to the schema, but it probably will take some time.

[duncanbeevers]

I poked at this for a little while today, and encountered promising behavior.

• VSCode Tooltips are driven by the title property, not description both title and description field values.
• Embedding \n\n is unsightly, and is unlikely to be accepted upstream
• The Specification documentation is fairly well-structured

diff --git a/schema/openapi-3.0-2019-04-02.json b/schema/openapi-3.0-2019-04-02.json
index a36d749..3eb3f61 100644
--- a/schema/openapi-3.0-2019-04-02.json
+++ b/schema/openapi-3.0-2019-04-02.json
@@ -66,6 +66,7 @@
     },
     "Info": {
       "type": "object",
+      "title": "InfoObject\n\nThe object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.",
       "required": [
         "title",
         "version"

🥦 Generate title fields

Since the specification is fairly well-structured, it may be possible to extract some documentation from there and use it to augment the schema documents in this plugin.