RepreZen
Code Assist: stick with keywords as template names
KZOE code assist offers two types of suggestion: 1) keyword 2) template. At the moment templates are named inconsistently, or in a way that makes it harder to find them. For example, in the context of an empty spec:
Here code assist shows keywords in the same order as they are declared in the spec rather than alphabetically. I can find the keyword I need quickly, and as I use them they disappear from the code assist list. But the templates are harder to find. For a start, each on here is prefixed with ‘OpenAPI’. The first template is then named 'version' but it is a template for the 'openapi' element. The other two templates then use the keywords as template names.
Suggestion:
Use keywords, without a prefix, as the template name, except in cases where there's a need to distinguish between different variants. Note that there are such cases, where we want to present alternatives. Here's a n example:
https://www.dropbox.com/s/ff4kvsenrs4u0yz/2017-08-09%2007_39_39-Greenshot.png?dl=0
RAPID-ML also has multiple alternatives for property set. I think it's fine to do it this way, not name the templates after keywords where descriptive names are more communicative of the intent. But as a rule of thumb, only do this when there's more than one alternative template that could be used in the same context.
Use the template description to explain what the template is. For example: openapi: OpenAPI version declaration.
Make sure that the templates occur in the same order as the keywords (i.e. as per the lang spec)
Would it be better to use the object name used in the OpenAPI3 Specification at the template name, and to put the keyword in brackets afterwards if there is one?
For example, in Info Object we have Contact Object and License Object, both of which have keywords. These could be listed in code assist like this:
Contact Object (contact): The contact information for the exposed API. License Object (license): The license information for the exposed API.
On the other hand, in the context of the Paths Object, we have the Path Item Object, and this has no keyword. So this could be listed in code assist like this:
Path Item Object: A relative path to an individual endpoint.
At the moment this template is named using RAPID-ML terminology:
Object resource: object resource template
It would definitely be better to stick to names from the Open API specification.
Would it be better to use the object name used in the OpenAPI3 Specification at the template name, and to put the keyword in brackets afterwards if there is one?
I wouldn't recommend that. It's important to the spec, but it's generally not the vocabulary that most developers would be used to. The concrete syntax is what's most familiar to them.
