[Swagger][OpenAPI] Add "id" path parameter for POST item operation

Author: teohhanhui

src/Swagger/Serializer/DocumentationNormalizer.php

@@ -390,13 +390,7 @@ private function updateGetOperation(bool $v3, \ArrayObject $pathOperation, array
 
         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Retrieves a %s resource.', $resourceShortName);
 
-        $parameter = [
-            'name' => 'id',
-            'in' => 'path',
-            'required' => true,
-        ];
-        $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
-        $pathOperation['parameters'] ?? $pathOperation['parameters'] = [$parameter];
+        $pathOperation = $this->addItemOperationParameters($v3, $pathOperation);
 
         $successResponse = ['description' => sprintf('%s resource response', $resourceShortName)];
         if ($responseDefinitionKey) {
@@ -424,6 +418,11 @@ private function updatePostOperation(bool $v3, \ArrayObject $pathOperation, arra
 
         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Creates a %s resource.', $resourceShortName);
 
+        $userDefinedParameters = $pathOperation['parameters'] ?? null;
+        if (OperationType::ITEM === $operationType) {
+            $pathOperation = $this->addItemOperationParameters($v3, $pathOperation);
+        }
+
         $responseDefinitionKey = false;
         $outputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output', ['class' => $resourceClass], true);
         if (null !== $outputClass = $outputMetadata['class'] ?? null) {
@@ -460,12 +459,12 @@ private function updatePostOperation(bool $v3, \ArrayObject $pathOperation, arra
                 'description' => sprintf('The new %s resource', $resourceShortName),
             ];
         } else {
-            $pathOperation['parameters'] ?? $pathOperation['parameters'] = [[
+            $userDefinedParameters ?? $pathOperation['parameters'][] = [
                 'name' => lcfirst($resourceShortName),
                 'in' => 'body',
                 'description' => sprintf('The new %s resource', $resourceShortName),
                 'schema' => ['$ref' => sprintf('#/definitions/%s', $requestDefinitionKey)],
-            ]];
+            ];
         }
 
         return $pathOperation;
@@ -480,13 +479,7 @@ private function updatePutOperation(bool $v3, \ArrayObject $pathOperation, array
 
         $pathOperation['summary'] ?? $pathOperation['summary'] = sprintf('Replaces the %s resource.', $resourceShortName);
 
-        $parameter = [
-            'name' => 'id',
-            'in' => 'path',
-            'required' => true,
-        ];
-        $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
-        $pathOperation['parameters'] ?? $pathOperation['parameters'] = [$parameter];
+        $pathOperation = $this->addItemOperationParameters($v3, $pathOperation);
 
         $responseDefinitionKey = false;
         $outputMetadata = $resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'output', ['class' => $resourceClass], true);
@@ -540,13 +533,17 @@ private function updateDeleteOperation(bool $v3, \ArrayObject $pathOperation, st
             '404' => ['description' => 'Resource not found'],
         ];
 
+        return $this->addItemOperationParameters($v3, $pathOperation);
+    }
+
+    private function addItemOperationParameters(bool $v3, \ArrayObject $pathOperation): \ArrayObject
+    {
         $parameter = [
             'name' => 'id',
             'in' => 'path',
             'required' => true,
         ];
         $v3 ? $parameter['schema'] = ['type' => 'string'] : $parameter['type'] = 'string';
-
         $pathOperation['parameters'] ?? $pathOperation['parameters'] = [$parameter];
 
         return $pathOperation;