Swagger UI is not accessible compliant

[ghost]

Content & configuration

Is your feature request related to a problem?

Hi Team, We have taken a strong dependency on swagger-ui-dist package in one of our projects. When we went through the accessibility compliance review, we received 28 sev1/sev2 issues. We have observed similar requests earlier raised by other developers, but it's not addressed for 2+ years yet.

https://github.com/swagger-api/swagger-ui/issues/5290 https://github.com/swagger-api/swagger-ui/issues/5248

I just want to know why these accessibility issues are not yet addressed? is there any specific reason?

Describe the solution you'd like

Since these issues are not taking care of for so long we are afraid to raise the PR and keep waiting. Is there any plan to address these accessibility-related PRs?

Describe alternatives you've considered

Currently, we are using one private fork to address these issues by knowing we will have maintenance challenges etc.

Additional context

Issue list for reference:

Issue Title	Severity
[Keyboard Navigation-Authorize]: Keyboard tab focus is moving twice to the check boxes present in the dialog.	3 - Medium
[Screen Readers-Authorize]: Screen readers are not narrating descriptive name role and state for the checkboxes present in the 'Available Authorization' dialog.	2 - High
[Supporting the Platform]: Expand collapsed chevrons and Unlock controls present in the End Points tab section is not visible highcontrast black mode.	2 - High
[Screen Readers]: JAWS is not identifying separately expand collapsed control and email ids present in the Revision history tab section navigating using JAWS Cursor mode.	2 - High
[Screen Readers-Authorize]: Screen readers are narrating role(button) information twice for the close(X) button present in the dialog	3 - Medium
[Keyboard Navigation-End Points]: Focus loss is observed after 'Copy to clip Board' button present in Server response -> Response Body section in the page when navigating using keyboard tab key.	3 - Medium
[Keyboard Navigation]: Keyboard tab focus is moving to the same functionality control thrice present in the 'Schema' section when navigating using keyboard tab key.	3 - Medium
[Keyboard Navigation]: Visual focus indicator is not visible for the 'Get', 'Put', 'Post', 'Patch' and 'Delete' request expand / collapse controls present in the 'End Points' tab section.	2 - High
[Keyboard Navigation-Authorize]: User is unable to Check / Uncheck the multiple check boxes present in the 'Authorize' dialog when navigating using keyboard ab key.	2 - High
[Screen Reader-OneCatalog-API Catalog Service(eStaorage)-End points]: Screen Readers are not narrating Name and Role for the 'Available authorizations' dialog	2 - High
[Screen Readers-Authorize]: Screen readers are narrating incorrect role as 'link' for the 'Select all' button and 'Select None' button present in Available Authorization dialog.	3 - Medium
[Screen Readers]: JAWS is not identifying 'Server Response' table in the page when navigating using table shortcut key 'T'	3 - Medium
[Keyboard Navigation]: Unable to close the 'Available Authorizations' dialog using 'esc' key..	3 - Medium
[Screen Reader]: JAWS focus is not sequential after performing action for the expand/Collapse controls present in the Schema Section while navigating in JAWS cursor mode(Down arrow key),	3 - Medium
[Keyboard Navigation]: Unable to access 'Tab' controls present in the page using arrow keys.	3 - Medium
[Keyboard Navigation-Authorize]: No alert message is getting displayed On invoking 'Authorize' button, without entering any data in value edit field.	2 - High
[Visual Requirements]: Luminosity ratio is less than the minimum contrast ratio 4.5:1 for the Nullable true text in the Schema value	2 - High
[Screen Reader)-Revision History]: JAWS focus is moving to top of the page on closing the confirmation dialog while navigating using down arrow	3 - Medium
[Screen Readers]: Screen readers are narrating role information twice for the 'Authorize' buttons present next to the expand / collapse request controls in the page.	4 - Low
[Keyboard Navigation]: Focus loss is observed on invoking the 'Clear' button present in the Parameters section when navigating using keyboard tab key.	3 - Medium
[Screen Readers]: Screen readers are narrating unnecessary table information for the elements present in the expanded section of Schema in the responses.	3 - Medium
[Screen Readers]: Rows and Columns are not mapped with each other for 'Server Response' and 'Responses' table data cells in the page when navigating using table shortcut keys(Ctrl+Alt+Arrow keys).	3 - Medium
[Screen Readers]: Screen readers are not narrating Response displayed and cleared information on invoking the 'Execute' and / 'Clear' buttons.	3 - Medium
[Screen Readers]: Screen readers are not narrating focused button information on invoking the 'Try it Out' and / 'Cancel' buttons.	3 - Medium
[Screen Readers]: Screen readers are narrating two roles for the tab controls present in 'eStorage' page.	3 - Medium
[Screen Readers]: Screen readers are not narrating name and state for the 'expand/collapse' controls present in the 'End Points' tab section.	2 - High
[Supporting the platform]: At 125% zoom mode Multiple Controls present in 'Available Authorizations' dialog are not visible.	2 - High
[Screen Readers]: Screen Readers are not narrating search results while entering data in the search edit field.	3 - Medium
[Visual Requirements]: Luminosity ratio is less than minimum required ratio of 3:1 for Authorize (Unlock) button icon's in the page.	3 - Medium
[Keyboard Navigation-Authorize]: Keyboard Focus is moving out of the dialog while navigating using tab key.	2 - High
[Visual Requirements]: Luminosity ratio is less than minimum required ratio of 4.5:1 for edit fields place holder text.	3 - Medium
[Screen Readers]: Screen readers are not narrating name for the 'Servers' combo box present in the 'End Points' tab section while navigating using Form mode(F).	2 - High
[Visual Requirements]: Luminosity ratio is less than minimum required ratio of 3:1 for 'Media Type' dropdown	3 - Medium
[Screen Reader]: Screen reader is not narrating the label information for the The API validation metadata details model edit field while navigating in NVDA forms mode 'F'	2 - High
[Screen Reader]: Screen reader is not narrating any information after user invokes Copy to clipboard control while navigating in NVDA browse mode(Down arrow key).	2 - High
[Screen Reader]: Screen reader is not narrating the Name role and state for the expand/Collapse controls present in the Schema Section while navigating in NVDA browse mode(Down arrow key),	2 - High
[Screen Reader]: Screen reader is not narrating the Required information for the mandatory fields present in the page while navigating in Forms mode 'F'.	3 - Medium
[Screen Readers-]: Screen readers are not narrating name for the close(X) button present in the dialog.	2 - High
[Screen Reader]: Screen reader is not narrating the table Summary for the Multiple tables present in the page.	3 - Medium
[Visual Requirements]: Alternative text tooltip is not defined for the 'Authorize' icon and 'Copy to clipboard' icon present in the page	3 - Medium
[Visual Requirements]: Luminosity ratio is less than the minimum contrast ratio 4.5:1 for the Multiple text present in the page	2 - High
[Screen Reader]: Screen Reader is not narrating the error suggestion for the Error occurred fields when press enter on the Execute button without entering the mandatory fields.	2 - High
[Keyboard Navigation]: Visual Focus indicator is not visible for the multiple controls present in the 'End Points' tab section, While navigating using keyboard tab key.	2 - High
[Keyboard Navigation]: Keyboard focus is not moving error caused fields when user press enter on the Execute button without entering the mandatory fields.	3 - Medium
[Screen Readers]: Incorrect heading levels are provided for the multiple headings in the end points tab.	3 - Medium
[Screen Readers]: Screen readers are not narrating role and state for the request expand / collapse controls present in the End Points tab.	2 - High
[Keyboard Navigation]: ‘Search endpoints’ placeholder text does not meets the minimum luminosity ratio of 4.5:1.	2 - High
[Keyboard Navigation]: Keyboard focus is not moving to the 'Example value' data section in the Responses section of expanded.	2 - High
[Keyboard Navigation-Authorize]: Keyboard focus is not moving to the multiple controls present in the 'Available authorizations' dialog, while navigating using keyboard ab key.	2 - High
[Keyboard Navigation]: Keyboard focus is not moving to the multiple controls in the Responses section of expanded request sections.	2 - High
[Keyboard Navigation]: Keyboard focus is not moving to the 'Get', 'Put', 'Post', 'Patch' and 'Delete' request expand / collapse controls in the 'End Points' tab section	1 - Critical

[ponelat]

Hi @satprpa thank you for pushing the a11y agenda! To see where we're at, I took a look at https://github.com/swagger-api/swagger-ui/issues/5290 and at least some of the items appear to be resolved (Chrome 90, Linux/Gnome3). I'd like to find time to test more, particularly around screen readers and the contrast ratios.

May I ask a few questions?

• How was the report above produced?
• Do you know if the JAWS/NVDA tools provide suggestions on what would fix their issues? (I'm unfamiliar with these tools, but hopefully they suggest semantic fixes that are general).
• Given there is one Critical issue in the above report, how can it be reproduced? It appears to work for me.
• Are you able to link to your fork or is it to remain private for now?

As far as PRs go, large ones are harder to get merged than smaller ones. Smaller PRs are able to get reviewed/addressed much quicker. If there are features that aren't applicable to the project it may be feasible to build them into a plugin, so that you don't need to maintain a private fork (which can be PITA :D ). Cast your eyes across the plugin system to see what's possible: https://github.com/swagger-api/swagger-ui/blob/master/docs/customization/plugin-api.md

And once again, thank you for helping more people with their APIs through accessibility! cc @frantuma @char0n

[ghost]

Hello @ponelat ,

Thanks a lot for your response. Pls find response to your questions below.

How was the report above produced? We have used following tools to check/report these issues.

1. Keyboard
2. Accessibility Insight Chrome/Edge extension https://accessibilityinsights.io/docs/en/web/overview/
3. High contrast mode (can be enabled windows, just search High contrast),
4. NVDA - NVDA (Non-Visual Desktop Access) is an open source screen reader for Windows developed by NV Access, a registered charity and software development company. NVDA has third-party add-ons that allow more customization for users. It provides both speech and braille output. Blind and visually impaired users in 120 countries use NVDA in 43 languages. You can download using https://www.nvaccess.org/download/
5. JAWS - JAWS (Job Access with Speech) is a screen reader for Windows made by Freedom Scientific. First released in 1995, it is a relatively expensive program for users to purchase but it can be customized into a powerful tool. It provides speech and braille output. It's used by blind or visually impaired users - including Deafblind users who rely on braille output. Since there is a license involved for JAWS you can ignore. If something works in NVDA that typically works in JAWS as well.

Do you know if the JAWS/NVDA tools provide suggestions on what would fix their issues? (I'm unfamiliar with these tools, but hopefully they suggest semantic fixes that are general). They don't suggest what needs to be done. But it's simple, it should read and interact with text and buttons etc. on the screen.

Given there is one Critical issue in the above report, how can it be reproduced? It appears to work for me. I will share recorded video of all the issues soon for your reference (working on that). It will be very easy for you to understand what we are talking about or will arrange one discussion.

Are you able to link to your fork or is it to remain private for now? This is something I can't share at the moment since it's private. I will work on this further to share the changes with you post our discussion.

Hope it clarifies your queries. Looking forward to collaberate on these issues with you soon!

[ghost]

Hello @ponelat,

PFA document, it contains all these issues with repro steps, expected behavior, evidence videos etc.

https://drive.google.com/file/d/1jET5FqdZZ3EcqqoNj3BncWe_DqZcXNgE/view?usp=sharing

Would love to have a call if you are interested. We can discuss the plan to fix all of these issues. Pls let me know.

cc: @frantuma @char0n

Note: Pls open the above URL by copying & pasting the link in a different tab rather than clicking on it directly

[ghost]

Hello @ponelat ,

Any update on this?

cc: @frantuma @char0n

[char0n]

@satprpa you did a great job mapping the issues; please give us some time to properly analyze your evidence provided in attached google doc. We're looking into it now.

[ghost]

Hello @char0n Have you guys done any progress on these issues? If yes can you pls share the release plan/date? Thanks

@frantuma @ponelat

[ponelat]

@satprpa thanks for your patience. Will update you soon on this issue, and the steps we can do going forward.

[ponelat]

@satprpa if you're on Twitter, could you reach out and we can organize a chat? My handle is https://twitter.com/jponelat

[ghost]

Hey @ponelat I followed you on twitter. Pls follow me back with this handle https://twitter.com/spparida. Then we can start chat I believe.

[ponelat]

As discussed, going to start with a PR for keyboard navigation and work from there. Looking forward to the collaboration!

[Chi-teck]

I think, in order to make the UI accessible, we first need to fix elementary errors in the HTML markup.

Consider servers dropdown.

<div>
    <span class="servers-title">Servers</span>
    <div class="servers">
        <label for="servers">
            <select>
                <option value="https://example.com">https://example.com - Production Server</option>
            </select>
        </label>
    </div>
</div>

Why was it done this way?

Most of accessibility violations will disappear once we bring the markup in compliance with the HTML specification.

[danbivins]

Are the above issues being dealt with or is there a reason this has gone stale?

[ghost]

We use Sort Site and are getting multiple Level A accessibility violations. Should we file a new issue to get these addressed?

[msftedad]

Hi, I would like to confirm what is the expected ETA for fixing accessibility issues for Swagger UI. We have Mutiple issues for Swagger, it seems all swagger UI accessibility issues are merged here. It would be helpful if we can have a tentative ETA or progress status on these issues?