API Document Generators Can Fall Woefully Short on Meeting Accessibility Guidelines – InApps 2022

Thanks to standardization, API specification files are increasingly being used in automated build systems, and can even be used to auto-generate documentation. There comes a cost to this automation, however, as the products of these systems often fail to meet accessibility guidelines, potentially preventing the disabled from accessing this information and services.

SwaggerUI may be one of the most popular choices and is an easy way for API providers to quickly create interactive API documentation, but community members have been asking for SwaggerUI to conform to accessibility standards for over a year now, and there has been little response from the SwaggerUI team to date. Many organizations want, or even may be required under Federal law, to meet Section 508 accessibility standards, which are modeled on the W3C’s Web Accessibility Guidelines 2.0.

Since January 2016, Swagger’s management at SmartBear has been aware of the lack of compliance. “We’re aware of 508 but haven’t done any special work to be compliant with it,” Swagger developer evangelist Ron Ratovsky wrote. Instead, Ratovsky suggests individual users can customize SwaggerUI themselves. Some have gone on to do that, according to a still-open, still-unassigned issue opened on 14 June 2016.

It is a vicious cycle: SwaggerUI’s project team may not be particularly fussy about making their documentation tool accessible to people with disabilities as they may not see that as a large part of their community of users.

This year’s Stack Overflow developer survey found 3.4 percent of respondents were comfortable identifying they had a disability. If that was the same proportion amongst the SwaggerUI community, based on their 8,076 starred followers on GitHub, that would represent 275 users. The project team might not see 275 users as being a big enough group to prioritize their documentation needs.

SwaggerUI is one of the principle ways across the API industry to autogenerate documentation. It is usually the first way that new API providers quickly create documentation for their community. SwaggerUI takes an API specification file, like the Open API Initiative format (OAS) and autogenerates documentation that is then embedded as an interactive sandbox in the API provider’s developer portal. So not having access to readable API documentation could lock developers with disabilities out of potential employment and participation opportunities.

“In attempting to incorporate Swagger UI in a government API project, I discovered that Swagger UI needs a considerable amount of work to bring it up to 508 compliance,” said engineer Joe Adkins, founder member of the creative production group The Misery Brothers, who has previously identified this as an issue in the SwaggerUI GitHub repo.

Adkins says the lack of compliance of the SwaggerUI with disability accessibility standards “is somewhat surprising, given that it is used for numerous government projects. There are a number of cosmetic and surface-type things one may do (like contrast, labeling, etc) to help in this regard, and some other community members have made improvements in this area. But that still leaves considerable front end development required in order to make Swagger UI a POUR-ous/508-compliant app. As I recall, the work needed was non-trivial but doable. It’s kind of amazing how little government development contractors pay attention to accessibility and usability, and just use tools like this with no plans to customize.”

The Importance of API Specs in Future Automation

API specification files are increasingly being used to enable automated continuous integration/continuous delivery (CI/CD) pipelines, which make product builds faster and more stable.  But API specification files are also being used to auto-generate documentation and reference guides.

API Specification formats like Open API Initiative are becoming increasingly essential for enterprises looking to manage their CI/CD workflows. Integrating builds, and autogenerating documentation and resources like SDKs are already becoming the main harnessing power of an API specification.

Open API version 3.0 is not generally available as yet, with an RC 2 published on GitHub for comment. Tool makers are already adopting to the standard, however. Recently, RepreZen updated its API design tool, API Studio, and its open source KaiZen editor for the Eclipse IDE, are both now available with Open API version 3.0 support.

Ted Epstein, RepreZen CEO, says he wanted to make the new specification available in the company’s product ahead of the inevitable scrambling that will come as more API lifecycle tools incorporate the new OAS version into their products over the next eighteen months.

Originally, the idea for documenting the API metadata in a specification may have been to make it more discoverable in search, or to provide an easy way for a developer to quickly understand the capabilities of an API before consumption, but it has been the automation use cases that are spearheading much of the interest in actually using a specification file. But like black box algorithms that recreate systemic barriers from the implementation decisions of their developer creators, API specifications for automating processes may have similar potential ill effects.

“This is an overall theme in API design: to ensure machine-readable API descriptions like OAS are considered first class source code. The code generation you create from the API description becomes part of your automated build process and you want to be able to manage it as part of the source code. It is like a compiler in a way,” said Epstein.

RepreZen’s API Studio is used by a range of non-profits, educational startups and a growing number of medium-sized companies and enterprises like the Swiss fintech Finnova, while enterprises like PayPal and Fannie Mae are also using the tool. Epstein says that especially amongst these users, API specification files are being taken up for CI/CD enablement.

“They are writing the API description in API Studio, or they might import their work as a one-off when they start to use API Studio,” said Epstein. “Then our tool is the primary environment for writing and editing the description and for ad hoc sandbox testing.

When the API is at a stable point for the organization, API Studio generates an API scaffold, or scaffolding code, which is automatically-generated code blocks based on the API description. These are stored in a generated code folder. A user would also create hand-crafted implementation code, which would document the business logic, data access and any data manipulation needed.

By using API descriptions with tools like API Studio, users can mix and match automation tools. Epstein says a fairly typical progression for new API providers is to feed the OAS file into SwaggerUI to automatically create the API reference documentation. Then over time, the API provider might add its own written API documentation.

Other documentation generator tools like ReDoc and Slate also use API specification file a to auto-generate their documentation.

Feature image: By Matthew Hamilton on Unsplash.com