Background

As part of FY2425 WE5.1, the MediaWiki team implemented support for automatically generating and translating OpenAPI specs for the MediaWiki REST APIs. The specific hypothesis text reads:

*If we release an interactive documentation sandbox for MediaWiki REST APIs, we will guarantee that our API documentation is fully up to date, testable, and localized for generations of global developers. This will introduce a repeatable pattern for documentation management that improves API stability.*

The REST sandbox delivered as part of this hypothesis uses Swagger UI for documentation visualization, which does not support native translation. This causes a less-than-ideal mixed experience for readers, where endpoint and parameter descriptions are translated, but overall UI elements (eg: table headers, button labels) remain in English.

Problem Statement

Developers would benefit from an interactive documentation sandbox for MediaWiki REST APIs. API sandboxes generated using OpenAPI specs are a common feature for modern web APIs, and there are several open source solutions available. However, no third party solution directly supports internationalization at the level generally expected of WMF wikis.

To make our API sandbox more maintainable, more aligned with our mission of accessible knowledge in 300+ languages, and more delightful for our developers to use, we would like to create a resuable documentation visualization and sandbox experience using Codex. Additionally, although the current sandbox only serves MediaWiki REST APIs, creating a reusable sandbox solution will also allow us to iteratively deliver a more consistent documentation experience across all Wikimedia REST APIs.

Conditions of acceptance

• Create a wireframe (or high fidelity mock) of an interactive API sandbox using Codex.
  • The design accounts for dark mode.
  • The design accounts for RTL reading modes.
• Create a technical design for making this a repeatable mechanism for all API authors.
  • The design must be reusable across Wikimedia APIs, where it can be dynamically generated using OpenAPI specs. In other words, we will not know the specific content of a given API, and would instead build towards the standard components that are expected within the OpenAPI specification.
• [Stretch] Implement the solution for MediaWiki REST APIs as part of the Wikimedia Hackathon.