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

Our OpenAPI specifications do not currently include response body definitions, meaning the specs are incomplete. Additionally, responses are not included in the REST Sandbox, limiting its usefulness for developers who wish to use the MediaWiki REST API. 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.

Conditions of acceptance

• Use mechanism defined in https://phabricator.wikimedia.org/T376290 to reference and inject response bodies into the OpenAPI schema for all ‘page’ endpoints and HTTP status codes.
  • POST: w/rest.php/v1/page
  • GET: w/rest.php/v1/page/{title}
  • PUT: w/rest.php/v1/page/{title}
• Verify ‘page’ endpoints now display response bodies in the REST Sandbox on the test wiki.
• Demonstrate the behavior through a demo for the MWI team.

Dependencies

This work depends on: https://phabricator.wikimedia.org/T376290 to be completed first.
This work also assumes that the JSON schemas for the ‘page’ endpoints are already defined: https://phabricator.wikimedia.org/T375530

Out of scope

Additional endpoints will be added after all JSON schemas have been defined.