Description

We are establishing a new pattern for defining response bodies as JSON schemas so they can be referenced directly as part of the OpenAPI spec generation. However, this is an untested pattern and needs a proof of concept for implementation.

Problem statement

The OpenAPI specifications are generated on demand, but currently do not contain complete responses in the spec. We took an initial approach of hardcoding responses as PHP arrays, but decided that will be too manual and arduous to maintain. Instead, we aligned on defining reusable JSON schema definitions that can be referenced then injected directly into the OpenAPI spec. However, we have not yet tested this approach and therefore need a proof of concept that can be referenced for repeating the pattern across MediaWiki endpoints.

• 1. Conditions of acceptance
• Create proof of concept for pulling and injecting response bodies into the generated spec. Proposal to start with GET: w/rest.php/v1/page/{title}
  • Schedule a knowledge sharing session with other members of the team to demonstrate the new pattern.
• Document instructions for how to follow a similar pattern across other endpoints.
  • Update related phab ticket with link to instructions, and/or additional details:

Out of scope

This work will only include an example that can be referenced. Replicating this pattern across endpoints will be covered in a separate ticket.