The sitemap endpoints mentioned in the description are a little uncommon in that they return application/xml rather than application/json. We always expected that handlers that do uncommon things would have to override things in uncommon ways (which still seems reasonable to me). I don't think that changes much in this task - we still do want a way to add examples in the general case - but it is worth pointing out that sitemap is a little unusual and therefore we should be careful when considering it as part of the general pattern.

For the proposed getResponseBodyExample() function, are we happy with embedding that directly in code as a php array, or do we want to add support for separating it out as an external file in the same way we do response schemas?

For context, here's an older task where we introduced the response schema files: T376290: Create example implementation for OpenAPI specs referencing response bodies inline . See the associated gerrit change for some discussion on the pros and cons of using an external file. Here's a relevant portion of @aaron 's comment on that change:

So, I can see some upsides:

Easier to use response specs outside of MediaWiki or even PHP.
With some caution, this supports response schema reuse for Handlers returning different subsets of the same collection.
Avoids slight awkwardness of describing JSON objects in PHP.

The downsides:

Slightly slower since the PHP array can use bytecode cache whereas this must read/parse the file.
Fragments aspects of each Handler into more places. Changing the response schema means updating the module(s) using it, so we have a module spec JSON file => handler => JSON file dependency.
Greater surface area for runtime errors (e.g. missing file). Currently mitigated by the mocha tests in CI.

That all seems relevant here too. I note that we've tended to use the external json files to describe response schemas, even though it is just as possible to override Handler::getResponseBodySchema and return them as PHP arrays.

If we support external json files for response examples, the process for creating an example will probably go something like:

1. call the endpoint in a real-world situation (at least from your local)
2. copy the json response into a .json file
3. manually edit the .json file to make the response more example-ish (replace specific page titles with example ones, replace any PII with fake data, etc.)
4. override a function named something like Handler::getResponseBodyExampleFileName() to reference the file

Of course, generateResponseSpec() would also be overrideable for any handler that preferred to use a PHP array, or had special needs (like sitemap does).

If we're unsure how useful external files would be, we could start the gerrit change without them, and try writing an example for one of the endpoints in core, preferable one with a complex response body, as a PHP array and see how convenient or inconvenient it feels.

Change #1299648 had a related patch set uploaded (by Aghirelli; author: Aghirelli):

[mediawiki/core@master] Rest: Add getResponseBodyExample() hook to Handler base class

https://gerrit.wikimedia.org/r/1299648

Change #1299648 merged by jenkins-bot:

[mediawiki/core@master] Rest: Add getResponseBodyExample() to Handler base class

https://gerrit.wikimedia.org/r/1299648

Resolving tasks as part of closing the sprint.