search

swagger-api / swagger-editor

Swagger Editor
https://editor.swagger.io
Apache License 2.0
8.95k stars 2.26k forks source link

Improve Validation Rendering #1704

Open webron opened 6 years ago

webron commented 6 years ago
Q A
Bug or feature request? Enhancement
Which Swagger/OpenAPI version? Any
Which Swagger-Editor version? Any
How did you install Swagger-Editor? N/A
Which browser & version? N/A
Which operating system? N/A

Currently, the validation errors are displayed directly on the right panel (swagger-ui). This is very distracting and blocks the view of the documentation.

The goal is to move the validation information to a collapsible panel at the bottom of the editor pane.

UX/UI Design Changes & Updated Design Rule Request

  1. Double-clicking an Error or Warning in the Validation Panel navigates the editor to that line.
  2. When the definition is navigated to the line, the line should be highlighted.
  3. The cursor goes to the exact point of where the error begins in the API definition.
  4. We should have classifications of 'errors' (Errors & Warnings).
  5. The validations panel should be able to resize bigger/smaller & fully collapse.
  6. When user collapses the validation panel and then reopens, panel should reopen at the last size that the user expanded or contracted the panel to be.
  7. The user can Open/Close the validation panel by clicking on the ( x INVALID) icon or anywhere on the collapsed panel row.
  8. When an error is 'fixed' and no longer exists, Error should be automatically removed from the list as well as the code indications that there is no longer an error/warning existing. User should be able to compare the error/warning list with the code as they are making changes and watch the error disappear from the list. Important for the validation panel to be static as I edit so that I can see the error go away.
  9. Line numbers should be a different color in case of an Error/Warning.
  10. When user mouses over error/warning line number, show a tooltip of error/warning.
  11. Line error/warning number color should move WHEN CODE lines move.
  12. Line number tooltips should not cover the line but rather show above or below so the user can compare the error to the line of code.
  13. Errors are triggered for a line *once the user cursor is onto a different line after a slight delay of 1-2 secs.
  14. When the script is Valid (No Errors or Warnings) the Validations panel does not open, it should stay collapsed when clicked on or user attempts to expand.
  15. Improve spacing in the gutter so that error/warning icons ALL align no matter how many digits the line number is. Possibly build numbers to the right opposed to the left where the line number cuts into the gutter space.

UI Mock

image

shockey commented 6 years ago

shockey commented 6 years ago

@webron:

Questions & notes

  1. Should Swagger-UI errors (e.g. fetch, auth, parser) continue to appear in the traditional Errors container, or are we replacing that entirely here?
  2. Are the icon assets used in the mockup available somewhere?
  3. Regarding 3, it's very easy to add column information to the goToLine call, but the quality of the start marks are limited by the subsystem producing the error data. Semantic validators don't send this data today, and would take a few days to retrofit.
  4. Does 9 imply that we should drop the gutter icons, or are we having icons and colored line numbers?
  5. I don't quite understand what 15 is getting at - on the technical side, it's not feasible to validate one line without walking its entire context today (The AST change-based system proposal would solve that limitation, but that's an entirely different conversation). That said, we can get a 1-2s delay for all errors updating after last user interaction for free, since we do that already.

Estimate

This should require 2-4 days to complete.

Item 17 is a potential snag point - tweaking Ace's internal stylesheets is a dice roll.

webron commented 6 years ago
  1. Great question. Will have to get back to you on that.
  2. Should be available, yes.
  3. I believe the main concern is first to get to the correct line. This is the current behavior, expect when the errors point to the wrong line.
  4. It's asking for both.
  5. Do you mean 13? Doesn't make sense with 15.

Item 17 doesn't exist! Is that means to be 15?

shockey commented 6 years ago

@webron yep, s/15/13 and s/17/15 😄 I pulled this into a text editor when I wrote my questions, and it was counting creatively.

webron commented 6 years ago

For 5 (13) - I believe the idea is to not trigger validation right away as that could drive the user nuts to see things change/flicker as they're typing.