API: Add support for documenting dynamic parameters

This will be used by AuthManager's API modules to document the fact that
AuthenticationRequest fields are accepted by the module, and to inform
the user reading the documentation how to determine what those are at
any particular time.

Change-Id: Ic7351de0f9bd239db17d584196e52a77112ed978

diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index 5f67a22..13d13a6 100644 (file)
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -637,6 +637,17 @@ abstract class ApiBase extends ContextSource {
         * @{
         */
 
+       /**
+        * Indicate if the module supports dynamically-determined parameters that
+        * cannot be included in self::getAllowedParams().
+        * @return string|array|Message|null Return null if the module does not
+        *  support additional dynamic parameters, otherwise return a message
+        *  describing them.
+        */
+       public function dynamicParameterDocumentation() {
+               return null;
+       }
+
        /**
         * This method mangles parameter name based on the prefix supplied to the constructor.
         * Override this method to change parameter name during runtime

diff --git a/includes/api/ApiHelp.php b/includes/api/ApiHelp.php
index 9bbb0b0..bbea20b 100644 (file)
--- a/includes/api/ApiHelp.php
+++ b/includes/api/ApiHelp.php
@@ -392,8 +392,9 @@ class ApiHelp extends ApiBase {
                        }
 
                        $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
+                       $dynamicParams = $module->dynamicParameterDocumentation();
                        $groups = array();
-                       if ( $params ) {
+                       if ( $params || $dynamicParams !== null ) {
                                $help['parameters'] .= Html::openElement( 'div',
                                        array( 'class' => 'apihelp-block apihelp-parameters' )
                                );
@@ -654,6 +655,17 @@ class ApiHelp extends ApiBase {
                                        }
                                }
 
+                               if ( $dynamicParams !== null ) {
+                                       $dynamicParams = ApiBase::makeMessage( $dynamicParams, $context, array(
+                                               $module->getModulePrefix(),
+                                               $module->getModuleName(),
+                                               $module->getModulePath()
+                                       ) );
+                                       $help['parameters'] .= Html::element( 'dt', null, '*' );
+                                       $help['parameters'] .= Html::rawElement( 'dd',
+                                               array( 'class' => 'description' ), $dynamicParams->parse() );
+                               }
+
                                $help['parameters'] .= Html::closeElement( 'dl' );
                                $help['parameters'] .= Html::closeElement( 'div' );
                        }

diff --git a/includes/api/ApiParamInfo.php b/includes/api/ApiParamInfo.php
index a808ac0..18ca0ab 100644 (file)
--- a/includes/api/ApiParamInfo.php
+++ b/includes/api/ApiParamInfo.php
@@ -387,6 +387,20 @@ class ApiParamInfo extends ApiBase {
                }
                ApiResult::setIndexedTagName( $ret['parameters'], 'param' );
 
+               $dynamicParams = $module->dynamicParameterDocumentation();
+               if ( $dynamicParams !== null ) {
+                       if ( $this->helpFormat === 'none' ) {
+                               $ret['dynamicparameters'] = true;
+                       } else {
+                               $dynamicParams = ApiBase::makeMessage( $dynamicParams, $this->context, array(
+                                       $module->getModulePrefix(),
+                                       $module->getModuleName(),
+                                       $module->getModulePath()
+                               ) );
+                               $this->formatHelpMessages( $ret, 'dynamicparameters', array( $dynamicParams ) );
+                       }
+               }
+
                return $ret;
        }