swagger-api / swagger-api/swagger-ui

Authorization buttons lack informative semantics

Open
#5,297 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog cat: a11y
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Authorization button semantic issues:

The main authorization button and per-operation authorization buttons have some issues with their accessible name and ARIA attributes:

  • The main authorization button does not communicate whether it is locked or unlocked in its name
  • The operation-specific authorization buttons use the word "button" in their name, which is redundant and will cause "button" to be announced twice
  • Operation-specific authorization buttons lack context about which operation they are associated with. This affects screen reader users who navigate by tab or by form control.
  • All buttons lack an indication that they open a dialog (e.g. through aria-haspopup)
Q&A (please complete the following information)
  • OS: Windows (also repros on macOS/VoiceOver and iOS/VoiceOver)
  • Browser: all
  • Version: all
  • Method of installation: n/a
  • Swagger-UI version: latest master
  • Swagger/OpenAPI version: n/a
Content & configuration

The issue repros on https://petstore.swagger.io, and I tested locally by cloning swagger-ui and running it locally off the master branch

Describe the bug you're encountering

Screen reader users lack some contextual information when they encounter authorization buttons.

To reproduce...

Fire up your screen reader of choice and navigate to the buttons in question

Expected behavior

Screen readers should announce "Authorize" + the state of the button (locked or unlocked) + the specific operation (if applicable) + the fact that it opens a popup

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the authorization buttons on petstore.swagger.io or a local Swagger UI checkout using a screen reader, then locate the components that render the main and operation-specific buttons. Done means their accessible names convey authorization state and operation context without redundant “button” wording, and indicate that they open a dialog.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
accessibility, frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.