Content-assist for Swagger

[tfesenko]

There is a basic content-assist for top-level elements:

Content-assist to nested element to be done

[tedepstein]

Nice!

[ghillairet]

Some updates on the state of the content assist.

The content assist for a yaml editor will not be so easy to implement so I suggest that we start with basic, simple features, and start augment it once we understand how to really implement content assist.

Basic features to be implemented:

• allow content assist only on beginning of line
• start allow content assist after user enter a few letters, should provide possible matches to finish word
• start allow content assist on non beginning of line

Before starting on more advanced features, those 3 should be done. The challenge here is to adapt the result of the Yaml parser (snakeyaml), to give us useful data. The current problem with the Yaml parser is that it does not give us an easy to traverse/manipulate AST.

The other challenge for code assist is to use the information from the Swagger JSON Schema and merge it with the Yaml AST, to obtain somehow the type of elements the user would need.

[tedepstein]

This is one of those areas where Xtext makes things much easier. So I agree with the strategy of starting with a minimal code assist feature, and adding more as we learn how.

But keep in mind that, at some point, it might be best to stop work on this Swagger editor, which we regard as "tactical", and start work on an Xtext-based Swagger editor, with more long-term strategic value. We will need to decide together when we have gotten to the point of diminishing returns with YEdit.

Also, @ghillairet , can you please clarify:

start allow content assist after user enter a few letters, should provide possible matches to finish word

IIUC, this means we would display suggestions, but only after the user types a few letters.

Did you mean to display these suggestions automatically, as the user types? Or display them on explicit invocation, using Ctrl-space or a similar command?

Also, did you mean that this requirement of typing the first few letters would apply to beginning-of-line code assist, or only to mid-line code assist?

[ghillairet]

Suggestions would not appear automatically, but when the user does Ctrl-space, at least for now.

The goal would be first to do it for beginning-of-line code assist first and see then if it is easily doable for other parts of a document.

I agree also that using Xtext could simplify the development of the editor, especially if newer versions allow to implement whitespace indentation based languages.

[tfesenko]

I just checked RAML editor in AnypointStudio, it's based on snake-yaml. They only provide content-assist for the root-level elements (in the very beginning of the line)

[ghillairet]

I have added the completion for when the user starts to enter an input. For the rest, when the user activates the completion, it will propose the list of keywords found in the swagger schema.

I also started to offer suggestions for values, it's quite limited for now. For example if the user has enter

swagger: 

and activates the code completion after the symbol : it will propose '2.0' as it is the only choice offer by the schema.

[ghillairet]

Also maybe it is worth looking at how content assist is implemented by the yaml editor in Spring IDE, see https://github.com/spring-projects/spring-ide/tree/master/plugins/org.springframework.ide.eclipse.boot.properties.editor.yaml/src/org/springframework/ide/eclipse/boot/properties/editor/yaml/completions

[ghillairet]

Just for info, the spring ide yaml editor seems to be based on Yedit and does support some kind of content assist.

[ghillairet]

To update on the Spring Yaml Editor content assist. It looks like it proposes templates for properties. The implementation seems specific for their use case and also depends on other classes from the Spring IDE that are related to content assist.

[ghillairet]

The work that concerns the content assist will be done on the branch develop.

The approach that I investigate will work according to this high level flow:

1. call content assist at line x
2. find yaml path of element at line x
3. find definition in schema for path
4. find actual data matching the path in JSON representation of document
5. create assist proposals from definitions and actual data (e.g. not propose already present properties)

Below some screenshots of this prototype (does not work for many cases)

[ghillairet]

Lots of improvements have been done on the content assist. The latest version is available in the branch develop.

Here is a preview of what it can do:

Under the hood it works as describe in my previous comment. There are still place for improvements and may have some bugs, but I think it is quite close to being ready.

[tedepstein]

Guillaume, this looks really good! Very glad to see that you have found a way to address this challenge. Please keep it moving forward, do your best to test & verify.

Hope you have a a good weekend, and we'll talk next week.

• Ted

[ghillairet]

I made some more improvements for the content assist, that includes case when user starts to enter letters, now the proposals are only the ones for the current context.

Still some things to improve, for example:

• content assist inside an object that only defines pattern properties.
• distinguishing required properties in the content assist popup.
• better looking labels in the popup (e.g. use of different colors)

[tfesenko]

There maybe some remaining minor issues, but the main part is done. Closing.