Merge "Improve REST API validation documentation"

2 files changed, 8 insertions, 0 deletions

diff --git a/includes/Rest/Handler.php b/includes/Rest/Handler.php
index ff8036b28258..e829f2b2f253 100644
--- a/includes/Rest/Handler.php
+++ b/includes/Rest/Handler.php
@@ -18,6 +18,9 @@ abstract class Handler {
 	/**
 	 * (string) ParamValidator constant to specify the source of the parameter.
 	 * Value must be 'path', 'query', or 'post'.
+	 * 'post' refers to application/x-www-form-urlencoded or multipart/form-data encoded parameters
+	 * in the body of a POST request (in other words, parameters in PHP's $_POST). For other kinds
+	 * of POST parameters, such as JSON fields, use BodyValidator instead of ParamValidator.
 	 */
 	public const PARAM_SOURCE = 'rest-param-source';
 
@@ -227,6 +230,10 @@ abstract class Handler {
 	 * Every setting must include self::PARAM_SOURCE to specify which part of
 	 * the request is to contain the parameter.
 	 *
+	 * Can be used for validating parameters inside an application/x-www-form-urlencoded or
+	 * multipart/form-data POST body (i.e. parameters which would be present in PHP's $_POST
+	 * array). For validating other kinds of request bodies, override getBodyValidator().
+	 *
 	 * @stable to override
 	 *
 	 * @return array[] Associative array mapping parameter names to
diff --git a/includes/Rest/Validator/BodyValidator.php b/includes/Rest/Validator/BodyValidator.php
index 6eeaf759ce5b..d0fece0e2411 100644
--- a/includes/Rest/Validator/BodyValidator.php
+++ b/includes/Rest/Validator/BodyValidator.php
@@ -9,6 +9,7 @@ use MediaWiki\Rest\RequestInterface;
  * Interface for validating a request body
  *
  * @stable to implement
+ * @see \MediaWiki\Rest\Handler::getBodyValidator()
  */
 interface BodyValidator {