REST: Specify param descriptions as MessageValue objects

Previously, parameter descriptions could only be specified as
strings. We want OpenAPI specs generated from parameter
definitions to be internationalizable, so allow specifying
descriptions as MessageValue objects, which can be translated
using normal MediaWiki mechanisms.

Bug: T376493
Change-Id: Ia91f2bca14730599658e05446931e1426adb9eae

10 files changed, 50 insertions, 10 deletions

diff --git a/includes/Rest/Handler/CompareHandler.php b/includes/Rest/Handler/CompareHandler.php
index b39d6bb263f2..8200537906a3 100644
--- a/includes/Rest/Handler/CompareHandler.php
+++ b/includes/Rest/Handler/CompareHandler.php
@@ -194,11 +194,13 @@ class CompareHandler extends Handler {
 				ParamValidator::PARAM_TYPE => 'integer',
 				ParamValidator::PARAM_REQUIRED => true,
 				Handler::PARAM_SOURCE => 'path',
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-compare-from' ),
 			],
 			'to' => [
 				ParamValidator::PARAM_TYPE => 'integer',
 				ParamValidator::PARAM_REQUIRED => true,
 				Handler::PARAM_SOURCE => 'path',
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-compare-to' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/LanguageLinksHandler.php b/includes/Rest/Handler/LanguageLinksHandler.php
index c213a2bf8ba4..e9465938d215 100644
--- a/includes/Rest/Handler/LanguageLinksHandler.php
+++ b/includes/Rest/Handler/LanguageLinksHandler.php
@@ -5,6 +5,7 @@ namespace MediaWiki\Rest\Handler;
 use MediaWiki\Languages\LanguageNameUtils;
 use MediaWiki\Page\ExistingPageRecord;
 use MediaWiki\Page\PageLookup;
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\Handler\Helper\PageRedirectHelper;
 use MediaWiki\Rest\Handler\Helper\PageRestHelperFactory;
 use MediaWiki\Rest\LocalizedHttpException;
@@ -158,6 +159,7 @@ class LanguageLinksHandler extends SimpleHandler {
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-language-links-title' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/MediaFileHandler.php b/includes/Rest/Handler/MediaFileHandler.php
index 3a6b161c1d2e..3c4c0acfda01 100644
--- a/includes/Rest/Handler/MediaFileHandler.php
+++ b/includes/Rest/Handler/MediaFileHandler.php
@@ -6,6 +6,7 @@ use File;
 use MediaFileTrait;
 use MediaWiki\Page\ExistingPageRecord;
 use MediaWiki\Page\PageLookup;
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\LocalizedHttpException;
 use MediaWiki\Rest\Response;
 use MediaWiki\Rest\SimpleHandler;
@@ -134,6 +135,7 @@ class MediaFileHandler extends SimpleHandler {
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-media-file-title' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/MediaLinksHandler.php b/includes/Rest/Handler/MediaLinksHandler.php
index 6e5a97fd1cb6..e789d4096639 100644
--- a/includes/Rest/Handler/MediaLinksHandler.php
+++ b/includes/Rest/Handler/MediaLinksHandler.php
@@ -5,6 +5,7 @@ namespace MediaWiki\Rest\Handler;
 use MediaFileTrait;
 use MediaWiki\Page\ExistingPageRecord;
 use MediaWiki\Page\PageLookup;
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\LocalizedHttpException;
 use MediaWiki\Rest\Response;
 use MediaWiki\Rest\SimpleHandler;
@@ -150,6 +151,7 @@ class MediaLinksHandler extends SimpleHandler {
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-media-links-title' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/ModuleSpecHandler.php b/includes/Rest/Handler/ModuleSpecHandler.php
index 29743bea8375..a497631f47f4 100644
--- a/includes/Rest/Handler/ModuleSpecHandler.php
+++ b/includes/Rest/Handler/ModuleSpecHandler.php
@@ -5,6 +5,7 @@ namespace MediaWiki\Rest\Handler;
 use MediaWiki\Config\Config;
 use MediaWiki\Config\ServiceOptions;
 use MediaWiki\MainConfigNames;
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\LocalizedHttpException;
 use MediaWiki\Rest\Module\Module;
 use MediaWiki\Rest\RequestData;
@@ -167,11 +168,13 @@ class ModuleSpecHandler extends SimpleHandler {
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-module-spec-module' ),
 			],
 			'version' => [
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_DEFAULT => '',
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-module-spec-version' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/OpenSearchDescriptionHandler.php b/includes/Rest/Handler/OpenSearchDescriptionHandler.php
index 78c565bebbde..ed186846c771 100644
--- a/includes/Rest/Handler/OpenSearchDescriptionHandler.php
+++ b/includes/Rest/Handler/OpenSearchDescriptionHandler.php
@@ -32,6 +32,7 @@ use MediaWiki\SpecialPage\SpecialPage;
 use MediaWiki\Utils\UrlUtils;
 use MediaWiki\Xml\Xml;
 use Wikimedia\Http\HttpAcceptParser;
+use Wikimedia\Message\MessageValue;
 
 /**
  * Handler for generating an OpenSearch description document.
@@ -188,6 +189,7 @@ class OpenSearchDescriptionHandler extends Handler {
 		return [
 			'ctype' => [
 				self::PARAM_SOURCE => 'query',
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-opensearch-ctype' ),
 			]
 		];
 	}
diff --git a/includes/Rest/Handler/PageHistoryCountHandler.php b/includes/Rest/Handler/PageHistoryCountHandler.php
index f5d2fa9f2ea4..1062ecf71141 100644
--- a/includes/Rest/Handler/PageHistoryCountHandler.php
+++ b/includes/Rest/Handler/PageHistoryCountHandler.php
@@ -6,6 +6,7 @@ use ChangeTags;
 use MediaWiki\Page\ExistingPageRecord;
 use MediaWiki\Page\PageLookup;
 use MediaWiki\Permissions\GroupPermissionsLookup;
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\Handler\Helper\PageRedirectHelper;
 use MediaWiki\Rest\Handler\Helper\PageRestHelperFactory;
 use MediaWiki\Rest\LocalizedHttpException;
@@ -701,6 +702,7 @@ class PageHistoryCountHandler extends SimpleHandler {
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-count-title' ),
 			],
 			'type' => [
 				self::PARAM_SOURCE => 'path',
@@ -709,16 +711,19 @@ class PageHistoryCountHandler extends SimpleHandler {
 					array_keys( self::DEPRECATED_COUNT_TYPES )
 				),
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-count-type' ),
 			],
 			'from' => [
 				self::PARAM_SOURCE => 'query',
 				ParamValidator::PARAM_TYPE => 'integer',
-				ParamValidator::PARAM_REQUIRED => false
+				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-count-from' ),
 			],
 			'to' => [
 				self::PARAM_SOURCE => 'query',
 				ParamValidator::PARAM_TYPE => 'integer',
-				ParamValidator::PARAM_REQUIRED => false
+				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-count-to' ),
 			]
 		];
 	}
diff --git a/includes/Rest/Handler/PageHistoryHandler.php b/includes/Rest/Handler/PageHistoryHandler.php
index cc311b61d478..60a01d5be1bb 100644
--- a/includes/Rest/Handler/PageHistoryHandler.php
+++ b/includes/Rest/Handler/PageHistoryHandler.php
@@ -6,6 +6,7 @@ use ChangeTags;
 use MediaWiki\Page\ExistingPageRecord;
 use MediaWiki\Page\PageLookup;
 use MediaWiki\Permissions\GroupPermissionsLookup;
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\Handler\Helper\PageRedirectHelper;
 use MediaWiki\Rest\Handler\Helper\PageRestHelperFactory;
 use MediaWiki\Rest\LocalizedHttpException;
@@ -430,21 +431,25 @@ class PageHistoryHandler extends SimpleHandler {
 				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-title' ),
 			],
 			'older_than' => [
 				self::PARAM_SOURCE => 'query',
 				ParamValidator::PARAM_TYPE => 'integer',
 				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-older-than' ),
 			],
 			'newer_than' => [
 				self::PARAM_SOURCE => 'query',
 				ParamValidator::PARAM_TYPE => 'integer',
 				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-newer-than' ),
 			],
 			'filter' => [
 				self::PARAM_SOURCE => 'query',
 				ParamValidator::PARAM_TYPE => self::ALLOWED_FILTER_TYPES,
 				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-pagehistory-filter' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/SearchHandler.php b/includes/Rest/Handler/SearchHandler.php
index 4c427acf068e..30bd7d2f49c7 100644
--- a/includes/Rest/Handler/SearchHandler.php
+++ b/includes/Rest/Handler/SearchHandler.php
@@ -24,6 +24,7 @@ use SearchEngineFactory;
 use SearchResult;
 use SearchSuggestion;
 use StatusValue;
+use Wikimedia\Message\MessageValue;
 use Wikimedia\ParamValidator\ParamValidator;
 use Wikimedia\ParamValidator\TypeDef\IntegerDef;
 
@@ -403,6 +404,7 @@ class SearchHandler extends Handler {
 				self::PARAM_SOURCE => 'query',
 				ParamValidator::PARAM_TYPE => 'string',
 				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-search-q' ),
 			],
 			'limit' => [
 				self::PARAM_SOURCE => 'query',
@@ -411,6 +413,7 @@ class SearchHandler extends Handler {
 				ParamValidator::PARAM_DEFAULT => self::LIMIT,
 				IntegerDef::PARAM_MIN => 1,
 				IntegerDef::PARAM_MAX => self::MAX_LIMIT,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-search-limit' ),
 			],
 		];
 	}
diff --git a/includes/Rest/Handler/TransformHandler.php b/includes/Rest/Handler/TransformHandler.php
index da96e291ecde..eb46243504ba 100644
--- a/includes/Rest/Handler/TransformHandler.php
+++ b/includes/Rest/Handler/TransformHandler.php
@@ -20,6 +20,7 @@
 
 namespace MediaWiki\Rest\Handler;
 
+use MediaWiki\Rest\Handler;
 use MediaWiki\Rest\Handler\Helper\ParsoidFormatHelper;
 use MediaWiki\Rest\HttpException;
 use MediaWiki\Rest\LocalizedHttpException;
@@ -40,18 +41,31 @@ class TransformHandler extends ParsoidHandler {
 	/** @inheritDoc */
 	public function getParamSettings() {
 		return [
-			'from' => [ self::PARAM_SOURCE => 'path',
+			'from' => [
+				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
-				ParamValidator::PARAM_REQUIRED => true, ],
-			'format' => [ self::PARAM_SOURCE => 'path',
+				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-transform-from' ),
+			],
+			'format' => [
+				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
-				ParamValidator::PARAM_REQUIRED => true, ],
-			'title' => [ self::PARAM_SOURCE => 'path',
+				ParamValidator::PARAM_REQUIRED => true,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-transform-format' ),
+			],
+			'title' => [
+				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
-				ParamValidator::PARAM_REQUIRED => false, ],
-			'revision' => [ self::PARAM_SOURCE => 'path',
+				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-transform-title' ),
+			],
+			'revision' => [
+				self::PARAM_SOURCE => 'path',
 				ParamValidator::PARAM_TYPE => 'string',
-				ParamValidator::PARAM_REQUIRED => false, ], ];
+				ParamValidator::PARAM_REQUIRED => false,
+				Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-transform-revision' ),
+			],
+		];
 	}
 
 	/**