search

swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.55k stars 8.96k forks source link

[Accessibility] WCAG 2.1 1.3.1, and 4.1.2 && Section 508 502.3.1 && Screen Reader Usability #5248

Open KimPlausible opened 5 years ago

KimPlausible commented 5 years ago

Q&A (please complete the following information)

Describe the bug you're encountering

Aggregated Accessibility Bugs related to WCAG 2.0 1.3.1 && Screen Reader Usability

  1. Narrator (screen reader) does not read the value against the Value label which is represented in the form of asterisks using Caps Lock arrow keys​. Screen reader users will not be able to understand the context of the asterisks because it's not read by the screen reader.​
  2. Name of the combo box "Schemes" is showing as "List items present inside the combo box".
  3. Narrator (screen reader) does not read the reference of column header (i.e. code details ,code and description). The user will not be able to understand the context of each column.
  4. Narrator (screen reader) reads the required field as asterisks only (id)(Present inside the delete which is part of Report section). The user will not understand that the field is required.
  5. Narrator (screen reader) does not read the "Error message" when we activate "Execute button". It reads the error message when we again move to the "Id field". The user will not be able to get the information about the error message within context.
  6. The name property of a focusable element must not be null.
  7. Name of combo box is showing as list items for Parameter content type.
  8. Narrator (screen reader) reads the state of the column as "Non selected", which is not required. The user will get confused when Narrator (screen reader) reads the unnecessary information.
  9. Narrator (screen reader) does not read the "Expand/Collapsed Status of the link (PUT/pet) ". The user will not be able to get the expand/collapsed status.
  10. Name of the group is missing.
  11. When Narrator (screen reader) users navigates within the table present under the "Responses" section, after reading the first row below header it announces "Example" and "Model" links. As a result, the screen reader users will confused and not able to understand the functionality effectively.
  12. The accordions provided on the page such as, "pet" etc. expand the content below upon activation. But for the same purpose, a button is also provided for expand/collapse labeled as "Expand/Collapse operation". If two different elements are provided for same functionality as discussed above, screen reader will be confused about the functionality and fail to use it.
  13. On the page, when screen reader users activates "Try it out", "Execute" buttons, the content gets dynamically changes. Regarding these no instruction or alert is provided. As a result, screen reader users not able to understand the same and fails to use it.
  14. The button provided on the page "Collapse operation" is markup using H4 which is inaccurate. Screen reader users navigates with navigation quick keys such as "B" for Button and "H" for Heading etc.; if multiple elements are used for marking a controls as discussed, then screen reader users will confused about the same and fails to understand.
  15. When screen reader users inputs value in the value text-field and activates "Authorize" button, the dialog content gets dynamically changes above. But no alert/feedback is announced for screen reader users. If no alert/feedback is announced, then screen reader users will not able to understand the same and fail to use it.
  16. When screen reader users activates the "Authorize " button, a dialog gets displayed on the screen which is not announced. Also, the screen reader users focus moves out of the dialog in the background. If no alert dialog is provided, screen reader users won't be aware about the presence of the dialog. Moreover, if the focus moves out of the dialog then, they will not able to distinguished between the background content and the dialog content.
  17. 'Value' form element missing label
  18. 'X' button on popup does not have Name
  19. Editable box for 'Value' does not have Name
  20. Name of "Parameters" and "Responses" tables missing
  21. Name property of 'Curl' is null
  22. Group (little expand carrot in subsection under 'Models') doesn't have Name
  23. Close modal button does not have discernable text
  24. reportPayload's Edit Value box missing Name
  25. Name of the cell is missing.

To reproduce...

Steps to reproduce the behavior

  1. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/ -> Authorize -> enter Value for api_key -> Authorize -> verify Value for updated field via screenreader
  2. https://petstore.swagger.io/ -> inspect element: combo box "HTTPS"
  3. https://petstore.swagger.io/ -> navigate to Response table for GET/pet/findByStatus -> Ctrl+Win+Enter to start Narrator in Windows -> Use Caps+Arrow keys to read out references of column headers
  4. https://petstore.swagger.io/#/pet/deletePet -> Ctrl+Win+Enter to start Narrator in Windows -> Use Caps+Arrow keys to read out the *required field
  5. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/#/user/deleteUser -> Try it out -> leave username field blank -> Execute -> navigate to username field for error message
  6. https://petstore.swagger.io/#/user/getUserByName -> Try it out -> input user1 in username field, inspect element: curl body
  7. https://petstore.swagger.io/#/pet/addPet -> inspect element: combo box "application/json-patch+json"
  8. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/#/pet/findPetsByStatus ->navigate to Parameters table -> Use Caps+Arrow keys to read out table values
  9. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/#/pet/updatePet -> expand and collapse PUT/pet operation
  10. https://petstore.swagger.io/#/ -> Models -> inspect element: group ""
  11. https://petstore.swagger.io/#/pet/findPetsByStatus -> Ctrl+Win+Enter to start Narrator in Windows -> navigate to Responses table -> Use Caps+Arrow keys to read Row2,Column2
  12. https://petstore.swagger.io/#/pet -> pet -> Expand operation
  13. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/#/store/getInventory ->
  14. https://petstore.swagger.io/#/ -> Inspect element: Expand/Collapse button
  15. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/#/ -> Authorize -> enter value for api_key -> Authorize
  16. Ctrl+Win+Enter to start Narrator in Windows -> https://petstore.swagger.io/#/ -> Authorize
  17. https://petstore.swagger.io/#/store/getInventory -> Available authorizations -> inspect Value edit box
  18. https://petstore.swagger.io/ -> Authorize -> inspect 'X' button for Close
  19. https://petstore.swagger.io/#/store/getInventory -> Available authorizations -> inspect Value edit box
  20. https://petstore.swagger.io/#/pet/findPetsByStatus -> Inspect "Parameters" & "Responses" tables
  21. https://petstore.swagger.io/#/pet/findPetsByStatus -> Try it out -> Execute -> inspect Curl
  22. https://petstore.swagger.io/#/ -> Models -> Order -> inspect Expand/Collapse carrot
  23. https://petstore.swagger.io/#/-> Authorize -> inspect 'X' button for Close
  24. https://petstore.swagger.io/#/pet/addPet -> Try it out -> Edit Value
  25. https://petstore.swagger.io/#/pet/deletePet -> inspect apiKey Description cell

Expected behavior

  1. Narrator (screen reader) should read the value against the Value label, which is represented in the form of asterisks, and should inform the user that the value is encoded and secured.​
  2. Name should be provided as "Schemes".
  3. Narrator (screen reader) should read the reference of column header (i.e. code and description).
  4. Narrator (screen reader) should read the mandatory field as required field.
  5. Narrator (screen reader) should read the error message when we activate "Execute" button.
  6. The name property of a focusable element must not be null.
  7. Name should be provided for combo box Parameter content type.
  8. Narrator (screen reader) should not read the state of the column as "Non selected".
  9. Narrator (screen reader) should read out the Expand/Collapsed state.
  10. Proper name should be provided for group.
  11. Table content should be announced accurately and in the structured manner for the benefits of screen reader users irrespective of screen reader used.
  12. Merge both link and button discussed above in single element for the benefits of screen reader users.
  13. Provide a hidden instruction about the dynamically updated contents for the benefits of screen reader users.
  14. The button should be removed from the H4 tag in the source code for the benefits of screen reader users.
  15. An alert or feedback should be announced when user activates the discussed button for the benefits of screen reader users.
  16. "Dialog" should be announced and popup start and popup end should be provided at the starting and ending of the dialog; alternatively, trap the user focus within the dialog.
  17. Form elements must have labels.
  18. Name should be provided as 'Close'.
  19. Name should be provided as 'Value'.
  20. Names should be provided for both tables as "Parameters" and "Responses", respectively.
  21. The name property of focusable element 'Curl' must not be null.
  22. Proper name should be provided for a group.
  23. Buttons must have discernable text.
  24. The name property of a focusable element must not be null.

Screenshots

  1. image

  2. image

  3. image

  4. image

  5. image

  6. image

  7. image

  8. image

  9. image

  10. image

  11. image

  12. image

  13. image

  14. image

  15. image

  16. image

  17. image

  18. image

  19. image

  20. image

  21. image

  22. image

  23. image

  24. image

  25. image

Additional context or thoughts

linelson commented 5 years ago

@shockey would you be open to a PR to fix these accessibility bugs as well as https://github.com/swagger-api/swagger-ui/issues/5247?

KimPlausible commented 5 years ago

Pri 0 (Blocking, high impact): 1, 4, 5, 7, 9, 13, 15, 16, 18, 23 Pri 1 (Blocking, low impact): 2, 11, 19, 20, 24 Pri 2 (Not blocking, high impact): 3, 6, 10, 14 Pri 3 (Not blocking, low impact): 8, 12, 17, 21, 22

msftedad commented 2 months ago

Hi @KimPlausible, is there any update on this bug, and could you please provide a tentative ETA for fixing it?