Provide user-friendly content-assist suggestions for patternProperties & pattern-constrained values

[tfesenko]

Extracted from #30 (comment):

The Swagger schema defines some patternProperties, including vendor extensions, path items and responses. It also defines some string values with pattern constraints, including host and basePath.

Code assist shows these patterns as suggestions, and there are two problems:

1. The patterns aren't a user-friendly indication of what is expected in this context.
2. The patterns, when chosen from the suggestion list, are inserted verbatim into the document, and they are not legal values.

Invoke content-assist for response code:

The first option is ([0-9]{3})$|^(default)$, choosing it will create an invalid model:

  /taxFilings:
    get:
      responses:
        ([0-9]{3})$|^(default)$:

PatternProperties are probably more useful in proposal description than for replacementString.

[tedepstein]

@ghillairet , I've been working through this problem with @tfesenko , and we would like to try using "title" to provide better labels for code assist suggestions.

• If you can retrieve the label I added to the schema in the task/70 branch, try displaying this as the suggestion.
• In this case, there's no value to insert, it just acts as a hint.

If this works, generally, we will want to make more use of the title property to provide better code assist (and possibly better validation errors).

[tedepstein]

Another improvement that would help with this: In the Responses context (when we have one), provide templates for the most common HTTP response codes, ideally with a description of each one.

[tedepstein]

I searched through the schema. Here are all of the contexts in which pattern and patternProperties are used:

Vendor Extensions:

  "patternProperties": {
    "^x-": {
      "$ref": "#/definitions/vendorExtension"
    }
  },

Host:

    "host": {
      "type": "string",
      "pattern": "^[^{}/ :\\\\]+(?::\\d+)?$",
      "description": "The host (name or ip) of the API. Example: 'swagger.io'"
    },

basePath:

    "basePath": {
      "type": "string",
      "pattern": "^/",
      "description": "The base path to the API. Example: '/api'."
    },

pathItem:

    "paths": {
      "type": "object",
      "description": "Relative paths to the individual endpoints. They must be relative to the 'basePath'.",
      "patternProperties": {
        "^x-": {
          "$ref": "#/definitions/vendorExtension"
        },
        "^/": {
          "$ref": "#/definitions/pathItem"
        }
      },
      "additionalProperties": false
    },

response:

    "responses": {
      "type": "object",
      "description": "Response objects names can either be any valid HTTP status code or 'default'.",
      "minProperties": 1,
      "additionalProperties": false,
      "patternProperties": {
        "^([0-9]{3})$|^(default)$": {
          "$ref": "#/definitions/responseValue"
        },
        "^x-": {
          "$ref": "#/definitions/vendorExtension"
        }
      },
      "not": {
        "type": "object",
        "additionalProperties": false,
        "patternProperties": {
          "^x-": {
            "$ref": "#/definitions/vendorExtension"
          }
        }
      }
    },

[tedepstein]

@daffinm raised another issue with these properties, and suggested a different resolution.

Most properties are static, so leaving the cursor after the colon after the user applies the keyword suggestion makes sense. But pattern property names need to be edited, post-insertion, and the cursor position doesn't allow for this. Templates might be a better solution for these pattern properties.

[daffinm]

Here is a gif I did showing this issue in action. I think templates might be the simplest solution.

[tedepstein]

Related issue #227