Added optional description field to the <route> tag in webapi.xml

app/code/Magento/AsynchronousOperations/Model/ConfigInterface.php

@@ -30,6 +30,7 @@ interface ConfigInterface
     const SERVICE_PARAM_KEY_INTERFACE = 'interface';
     const SERVICE_PARAM_KEY_METHOD = 'method';
     const SERVICE_PARAM_KEY_TOPIC = 'topic';
+    const SERVICE_PARAM_KEY_DESCRIPTION = 'description';
     const DEFAULT_HANDLER_NAME = 'async';
     const SYSTEM_TOPIC_NAME = 'async.system.required.wrapper.topic';
     const SYSTEM_TOPIC_CONFIGURATION =  [
@@ -48,7 +49,7 @@ interface ConfigInterface
      * @return array
      * @since 100.2.3
      */
-    public function getServices();
+    public function getServices(): array;
 
     /**
      * Get topic name from webapi_async_config services config array by route url and http method
@@ -59,5 +60,15 @@ public function getServices();
      * @throws \Magento\Framework\Exception\LocalizedException
      * @since 100.2.3
      */
-    public function getTopicName($routeUrl, $httpMethod);
+    public function getTopicName(string $routeUrl, string $httpMethod): string;
+
+    /**
+     * Get topic description from webapi_async_config services config array by route url and http method
+     *
+     * @param string $routeUrl
+     * @param string $httpMethod GET|POST|PUT|DELETE
+     * @return string
+     * @throws \Magento\Framework\Exception\LocalizedException
+     */
+    public function getTopicDescription(string $routeUrl, string $httpMethod): string;
 }

app/code/Magento/AsynchronousOperations/Model/MassSchedule.php

@@ -112,15 +112,24 @@ public function __construct(
      *
      * @param string $topicName
      * @param array $entitiesArray
+     * @param string $topicDescription
      * @param string $groupId
      * @param string $userId
      * @return AsyncResponseInterface
      * @throws BulkException
      * @throws LocalizedException
      */
-    public function publishMass($topicName, array $entitiesArray, $groupId = null, $userId = null)
-    {
+    public function publishMass(
+        $topicName,
+        array $entitiesArray,
+        $topicDescription = '',
+        $groupId = null,
+        $userId = null
+    ) {
         $bulkDescription = __('Topic %1', $topicName);
+        if ($topicDescription !== '') {
+            $bulkDescription = $topicDescription;
+        }
 
         if ($userId == null) {
             $userId = $this->userContext->getUserId();

app/code/Magento/Webapi/Model/Config/Converter.php

@@ -55,6 +55,10 @@ public function convert($source)
                 $soapMethod = trim($soapOperationNode->nodeValue);
             }
             $url = trim($route->attributes->getNamedItem('url')->nodeValue);
+            $description = '';
+            if ($descriptionNode = $route->attributes->getNamedItem('description')) {
+                $description = trim($descriptionNode->nodeValue);
+            }
             $version = $this->convertVersion($url);
 
             $serviceClassData = [];
@@ -104,6 +108,7 @@ public function convert($source)
                 ],
                 self::KEY_ACL_RESOURCES => $resourceReferences,
                 self::KEY_DATA_PARAMETERS => $data,
+                self::KEY_DESCRIPTION => $description
             ];
 
             $serviceSecure = false;

app/code/Magento/Webapi/Test/Unit/Model/Config/_files/webapi.php

@@ -70,6 +70,7 @@
                         'value' => '%customer_id%',
                     ],
                 ],
+                'description' => ''
             ],
         ],
         '/V1/customers/me' => [
@@ -88,6 +89,7 @@
                         'value' => null,
                     ],
                 ],
+                'description' => ''
             ],
             'PUT' => [
                 'secure' => true,
@@ -104,6 +106,7 @@
                         'value' => null,
                     ],
                 ],
+                'description' => ''
             ],
         ],
         '/V1/customers' => [
@@ -118,6 +121,7 @@
                 ],
                 'parameters' => [
                 ],
+                'description' => ''
             ],
         ],
         '/V1/customers/:id' => [
@@ -132,6 +136,7 @@
                 ],
                 'parameters' => [
                 ],
+                'description' => ''
             ],
             'DELETE' => [
                 'secure' => false,
@@ -145,6 +150,7 @@
                 ],
                 'parameters' => [
                 ],
+                'description' => ''
             ],
         ],
     ],

app/code/Magento/Webapi/etc/webapi_base.xsd

@@ -30,6 +30,7 @@
         <xs:attribute name="url" type="xs:string" use="required"/>
         <xs:attribute name="secure" type="xs:boolean"/>
         <xs:attribute name="soapOperation" type="xs:string"/>
+        <xs:attribute name="description" type="xs:string"/>
     </xs:complexType>
 
     <xs:complexType name="serviceType">

app/code/Magento/WebapiAsync/Controller/Rest/AsynchronousRequestProcessor.php

@@ -87,7 +87,7 @@ public function __construct(
     }
 
     /**
-     * {@inheritdoc}
+     * @inheritdoc
      */
     public function process(\Magento\Framework\Webapi\Rest\Request $request)
     {
@@ -99,11 +99,13 @@ public function process(\Magento\Framework\Webapi\Rest\Request $request)
 
         $entitiesParamsArray = $this->inputParamsResolver->resolve();
         $topicName = $this->getTopicName($request);
+        $topicDescription = $this->getTopicDescription($request);
 
         try {
             $asyncResponse = $this->asyncBulkPublisher->publishMass(
                 $topicName,
-                $entitiesParamsArray
+                $entitiesParamsArray,
+                $topicDescription
             );
         } catch (BulkException $bulkException) {
             $asyncResponse = $bulkException->getData();
@@ -119,8 +121,11 @@ public function process(\Magento\Framework\Webapi\Rest\Request $request)
     }
 
     /**
+     * Get topic name from request
+     *
      * @param \Magento\Framework\Webapi\Rest\Request $request
      * @return string
+     * @throws \Magento\Framework\Exception\LocalizedException
      */
     private function getTopicName($request)
     {
@@ -133,7 +138,24 @@ private function getTopicName($request)
     }
 
     /**
-     * {@inheritdoc}
+     * Get topic description from request
+     *
+     * @param \Magento\Framework\Webapi\Rest\Request $request
+     * @return string
+     * @throws \Magento\Framework\Exception\LocalizedException
+     */
+    private function getTopicDescription($request)
+    {
+        $route = $this->inputParamsResolver->getRoute();
+
+        return $this->webapiAsyncConfig->getTopicDescription(
+            $route->getRoutePath(),
+            $request->getHttpMethod()
+        );
+    }
+
+    /**
+     * @inheritdoc
      */
     public function canProcess(\Magento\Framework\Webapi\Rest\Request $request)
     {
@@ -148,6 +170,8 @@ public function canProcess(\Magento\Framework\Webapi\Rest\Request $request)
     }
 
     /**
+     * Check if path is bulk
+     *
      * @param \Magento\Framework\Webapi\Rest\Request $request
      * @return bool
      */

app/code/Magento/WebapiAsync/Model/Config.php

@@ -59,7 +59,7 @@ public function __construct(
     /**
      * @inheritdoc
      */
-    public function getServices()
+    public function getServices(): array
     {
         if (null === $this->asyncServices) {
             $services = $this->cache->load(self::CACHE_ID);
@@ -77,7 +77,29 @@ public function getServices()
     /**
      * @inheritdoc
      */
-    public function getTopicName($routeUrl, $httpMethod)
+    public function getTopicName(string $routeUrl, string $httpMethod): string
+    {
+        return $this->getServiceParameter($routeUrl, $httpMethod, self::SERVICE_PARAM_KEY_TOPIC);
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getTopicDescription(string $routeUrl, string $httpMethod): string
+    {
+        return $this->getServiceParameter($routeUrl, $httpMethod, self::SERVICE_PARAM_KEY_DESCRIPTION);
+    }
+
+    /**
+     * Get service parameter by name
+     *
+     * @param string $routeUrl
+     * @param string $httpMethod
+     * @param string $attributeName
+     * @return string
+     * @throws LocalizedException
+     */
+    private function getServiceParameter(string $routeUrl, string $httpMethod, string $attributeName): string
     {
         $services = $this->getServices();
         $lookupKey = $this->generateLookupKeyByRouteData(
@@ -91,7 +113,7 @@ public function getTopicName($routeUrl, $httpMethod)
             );
         }
 
-        return $services[$lookupKey][self::SERVICE_PARAM_KEY_TOPIC];
+        return $services[$lookupKey][$attributeName];
     }
 
     /**
@@ -101,7 +123,7 @@ public function getTopicName($routeUrl, $httpMethod)
      *
      * @return array
      */
-    private function generateTopicsDataFromWebapiConfig()
+    private function generateTopicsDataFromWebapiConfig(): array
     {
         $webApiConfig = $this->webApiConfig->getServices();
         $services = [];
@@ -111,6 +133,11 @@ private function generateTopicsDataFromWebapiConfig()
                     $serviceInterface = $httpMethodData[Converter::KEY_SERVICE][Converter::KEY_SERVICE_CLASS];
                     $serviceMethod = $httpMethodData[Converter::KEY_SERVICE][Converter::KEY_SERVICE_METHOD];
 
+                    $topicDescription = '';
+                    if (isset($httpMethodData[Converter::KEY_DESCRIPTION])) {
+                        $topicDescription = $httpMethodData[Converter::KEY_DESCRIPTION];
+                    }
+
                     $lookupKey = $this->generateLookupKeyByRouteData(
                         $routeUrl,
                         $httpMethod
@@ -123,9 +150,10 @@ private function generateTopicsDataFromWebapiConfig()
                     );
 
                     $services[$lookupKey] = [
-                        self::SERVICE_PARAM_KEY_INTERFACE => $serviceInterface,
-                        self::SERVICE_PARAM_KEY_METHOD    => $serviceMethod,
-                        self::SERVICE_PARAM_KEY_TOPIC     => $topicName,
+                        self::SERVICE_PARAM_KEY_INTERFACE   => $serviceInterface,
+                        self::SERVICE_PARAM_KEY_METHOD      => $serviceMethod,
+                        self::SERVICE_PARAM_KEY_TOPIC       => $topicName,
+                        self::SERVICE_PARAM_KEY_DESCRIPTION => $topicDescription
                     ];
                 }
             }
@@ -144,7 +172,7 @@ private function generateTopicsDataFromWebapiConfig()
      * @param string $httpMethod
      * @return string
      */
-    private function generateLookupKeyByRouteData($routeUrl, $httpMethod)
+    private function generateLookupKeyByRouteData(string $routeUrl, string $httpMethod): string
     {
         return self::TOPIC_PREFIX . $this->generateKey($routeUrl, $httpMethod, '/', false);
     }
@@ -161,7 +189,7 @@ private function generateLookupKeyByRouteData($routeUrl, $httpMethod)
      * @param string $httpMethod
      * @return string
      */
-    private function generateTopicNameFromService($serviceInterface, $serviceMethod, $httpMethod)
+    private function generateTopicNameFromService(string $serviceInterface, string $serviceMethod, string $httpMethod): string
     {
         $typeName = strtolower(sprintf('%s.%s', $serviceInterface, $serviceMethod));
         return strtolower(self::TOPIC_PREFIX . $this->generateKey($typeName, $httpMethod, '\\', false));
@@ -176,7 +204,7 @@ private function generateTopicNameFromService($serviceInterface, $serviceMethod,
      * @param bool $lcfirst
      * @return string
      */
-    private function generateKey($typeName, $methodName, $delimiter = '\\', $lcfirst = true)
+    private function generateKey(string $typeName, string $methodName, string $delimiter = '\\', bool $lcfirst = true): string
     {
         $parts = explode($delimiter, trim($typeName, $delimiter));
         foreach ($parts as &$part) {

app/code/Magento/WebapiAsync/Test/Unit/Model/ConfigTest.php

@@ -67,7 +67,8 @@ public function testGetServicesSetsTopicFromServiceContractName()
                         'service' => [
                             'class' => ProductRepositoryInterface::class,
                             'method' => 'save',
-                        ]
+                        ],
+                        'description' => ''
                     ]
                 ]
             ]