Page MenuHomePhabricator

Document how to preview changes to MediaWiki OpenAPI specs locally
Closed, ResolvedPublic

Description

When making a change to a field in a MediaWiki OpenAPI spec, I want to be able to preview my change in Special:RestSandbox locally before submitting a patch. I wasn't able to find any documentation for how to do this, so it would be great to have some docs available on mediawiki.org.

Event Timeline

Triage notes:

  • We should turn the sandbox on by default for developer environments to make it obvious.

We already have this in DevelopmentSettings.php:

$wgRestAPIAdditionalRouteFiles[] = 'includes/Rest/coreDevelopmentRoutes.json';
$wgRestAPIAdditionalRouteFiles[] = 'includes/Rest/content.v1.json';
$wgRestAPIAdditionalRouteFiles[] = 'includes/Rest/specs.v0.json';

This was necessary because the development modules had to be enabled for their tests to pass. But it is also convenient, and makes them available for use in the REST Sandbox.

Making them available in the sandbox would (currently) require adding something like this as well (this is taken from my LocalSettings.php):

$wgRestSandboxSpecs = [
	'mw' => [
		'url' => $wgScriptPath . '/rest.php/specs/v0/module/-',
		'name' => 'MediaWiki REST API',
	],
	'specs.v0' => [
		'url' => $wgScriptPath . '/rest.php/specs/v0/module/specs/v0',
		'name' => 'Specs API',
	],
	'content.v1' => [
		'url' => $wgScriptPath . '/rest.php/specs/v0/module/content/v1',
		'name' => 'Content API',
	],
];

There's no master "on/off" switch for the sandbox itself. The special page toggles itself based on the presence or absence of urls in the above config variable.

I'd still prefer to finish off T395719: [BLOCKED] REST: Beta Modules - automatic discovery with config override instead, but if that drags then maybe it is worth doing the above in the meantime.