Description

We have a new pattern for defining response bodies as JSON schemas so they can be referenced directly as part of the OpenAPI spec generation. This will allow us to complete the automated OpenAPI specifications so that they can display in a scalable and sustainable way. When this work is complete, users will be able to see example response bodies in the SwaggerUI test portal.

Problem statement

We need a way to include responses in the spec, so that our documentation is complete, and we can create a delightful experience for developers using our endpoints. We established a pattern for injecting the response bodies using defined JSON schemas, and now must replicate that behavior across all remaining endpoints in the MediaWiki REST API.

Conditions of acceptance

• Reference https://phabricator.wikimedia.org/T376294 for the pattern for how to implement.
• Replicate using the schemas to inject response bodies into the OpenAPI specs for the remaining REST API endpoints: https://www.mediawiki.org/wiki/API:REST_API/Reference#
  • Search
  • Transform
  • Media files
  • History
  • Additional page endpoints:
    • Metadata (bare)
    • HTML
    • Languages
    • Attached media
• Verify the response bodies are appearing correctly in the generated OpenAPI spec and Swagger UI view.
• Demo the complete coverage to the team.

Dependencies

Assumes https://phabricator.wikimedia.org/T376603 is complete, so that we can reference the JSON schemas directly to create the response bodies.

Out of scope

This work only covers the existing MediaWiki REST APIs. Action APIs, extensions, and other API experiences across the Wikimedia mission are not included in the scope of this work.