Cleaned up and improved testing of new XML attributes

snake14 · snake14 · commit b2b8564c780d · 2025-10-06T16:35:48.000+13:00
diff --git a/Annotations/AnnotationGenerator.php b/Annotations/AnnotationGenerator.php
@@ -957,7 +957,7 @@ public function convertExampleXmlToObject(string $xml): array
             // Handle any attributes
             $grouped = [];
             foreach ($node->attributes() as $attribute) {
-                $grouped['oaXmlAttributes'][] = [$attribute->getName() => (string) $attribute];
+                $grouped[OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME][] = [$attribute->getName() => (string) $attribute];
             }
 
             // Group children by tag name; repeated names become arrays
@@ -1142,8 +1142,13 @@ protected function buildMediaTypePropertiesArray(string $format, string $example
     {
         $contentType = $format === 'json' ? 'application/json' : ($format === 'xml' ? 'text/xml' : 'application/vnd.ms-excel');
 
-        $jsonSchema = $format === 'json' ? $this->buildSchemaAnnotationFromJsonExample(json_decode($exampleValue, true) ?? []) : [];
-        $xmlSchema = $format === 'xml' ? $this->buildSchemaAnnotationFromXmlExample(json_decode($exampleValue, true) ?? []) : [];
+        $decodedExampleValue = json_decode($exampleValue, true) ?? [];
+        $jsonSchema = $format === 'json' ? $this->buildSchemaAnnotationFromJsonExample($decodedExampleValue) : [];
+        $xmlSchema = $format === 'xml' ? $this->buildSchemaAnnotationFromXmlExample($decodedExampleValue) : [];
+        // If the XML example contains the temporary property to assist in building XML attributes in the schema, replace with newly encoded array with property removed
+        if ($format === 'xml' && strpos($exampleValue, OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) !== false) {
+            $exampleValue = json_encode($decodedExampleValue);
+        }
 
         if (in_array($format, ['json', 'xml'])) {
             // The annotation expects objects and not arrays, so replace [] with {}
@@ -1332,38 +1337,64 @@ public function buildPropertyAnnotationFromJsonExample(string $propName, array $
     /**
      * Take the deserialised structure of an XML node and build the lines of an OA\Schema annotation object for it.
      *
-     * @param array $xmlArrayObject Nested array of properties of the XML node.
+     * @param array $xmlArrayObject Nested array of properties of the XML node. Passed by reference so that temporary
+     * properties can be removed before the example is included in the annotations.
      * @param string $root Name of the root element. The default is 'result'.
      *
      * @return array Collection of potentially nested arrays representing an OA\Property annotation object.
      */
-    public function buildSchemaAnnotationFromXmlExample(array $xmlArrayObject, string $root = 'result'): array
+    public function buildSchemaAnnotationFromXmlExample(array &$xmlArrayObject, string $root = 'result'): array
     {
         $lines = [
             'type="object",',
             sprintf('@OA\Xml(name="%s"),', $root),
         ];
 
-        foreach ($xmlArrayObject as $key => $value) {
+        foreach ($xmlArrayObject as $key => &$value) {
             // If the value is not an array, skip
             if (!is_array($value)) {
                 continue;
             }
 
             if (count($value) === 1) {
                 $keys = array_keys($value);
-                // Skip if it's not a named property
+                // Skip if it's not a named property and isn't an array
                 if (!is_string(reset($keys)) && !is_array(reset($value))) {
                     continue;
                 }
             }
 
             $lines[] = $this->buildPropertyAnnotationFromXmlExample($key, $value);
+
+            // Recursively remove all instances of the temporary XML attributes property
+            $this->removeTempOaXmlAttributeProperty($value);
         }
 
         return ['@OA\Schema' => $lines];
     }
 
+    /**
+     * Iterate over a nested array representing an example response object and recursively remove all occurrences of the
+     * temporary property used to help build the schema for XML attributes.
+     *
+     * @param array $decodedExampleValue The reference to the nested array to remove the temporary property from.
+     *
+     * @return void
+     */
+    protected function removeTempOaXmlAttributeProperty(array &$decodedExampleValue): void
+    {
+        foreach ($decodedExampleValue as $key => &$value) {
+            if ($key === OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) {
+                unset($decodedExampleValue[$key]);
+                continue;
+            }
+
+            if (is_array($value)) {
+                $this->removeTempOaXmlAttributeProperty($value);
+            }
+        }
+    }
+
     /**
      * Take the deserialised structure of an XML node and build the lines of an OA\Property annotation object for it.
      *
@@ -1380,10 +1411,9 @@ public function buildPropertyAnnotationFromXmlExample(string $propName, array $v
             $type = 'array';
             // Merge the rows together to get as many properties as possible
             $mergedValues = [];
-            foreach ($values as $key => $value) {
-                $valueArray = is_array($value) ? $value : [$value];
+            foreach ($values as $value) {
                 if (is_array($value)) {
-                    $mergedValues = array_merge($mergedValues, $valueArray);
+                    $mergedValues = array_merge($mergedValues, $value);
                 }
             }
             $values = $mergedValues;
@@ -1405,7 +1435,7 @@ public function buildPropertyAnnotationFromXmlExample(string $propName, array $v
             }
 
             // Special handling for XML attributes
-            if ($key === 'oaXmlAttributes') {
+            if ($key === OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) {
                 $hasAttributes = true;
                 $childLines[] = $this->buildXmlAttributeSchemaLines($value);
                 continue;
@@ -1445,18 +1475,38 @@ public function buildPropertyAnnotationFromXmlExample(string $propName, array $v
         return ['@OA\Property' => array_merge($propertyLines, $childLines)];
     }
 
+    /**
+     * Build the array of lines for the attribute properties of an XML schema annotation object. It accepts an array of
+     * arrays representing the attributes of an XML node. It can also handle a single array of key/value pairs.
+     *
+     * @param array $attributes Collection of attributes and values. E.g. [['key1' => 'value1'],['key2' => 'value2']] or
+     * ['key1' => 'value1', 'key2' => 'value2']
+     *
+     * @return array The lines defining the property annotation objects for the XML attributes.
+     * E.g. [['@OA\Property' => ['property="idgoal",', 'type="string",', '@OA\Xml(attribute=true),', 'example="2"']]]
+     */
     public function buildXmlAttributeSchemaLines(array $attributes): array
     {
         $attributeSchemaLines = [];
         foreach ($attributes as $index => $attribute) {
-            $key = is_array($attribute) ? array_keys($attribute)[0] : $index;
-            $value = is_array($attribute) ? $attribute[$key] : $attribute;
-            $attributeSchemaLines[] = ['@OA\Property' => [
-                "property=\"$key\",",
+            $keys = is_array($attribute) ? array_keys($attribute) : [];
+            $key = count($keys) === 1 ? $keys[0] : $index;
+            $value = trim(is_array($attribute) ? $attribute[$key] ?? '' : $attribute);
+            // Allow attributes with empty values, but an attribute must always have a name
+            if (empty($key)) {
+                continue;
+            }
+            // Initialise with the lines that will always be present
+            $propertyLines = [
+                sprintf('property="%s",', $key),
                 'type="string",',
                 '@OA\Xml(attribute=true),',
-                "example=\"$value\"",
-            ]];
+            ];
+            // Add the example line if there's an actual value
+            if (!empty($value) || strlen($value) > 0) {
+                $propertyLines[] = sprintf('example="%s"', $value);
+            }
+            $attributeSchemaLines[] = ['@OA\Property' => $propertyLines];
         }
 
         return $attributeSchemaLines;
@@ -1506,6 +1556,9 @@ public function buildLinesForAnnotationObject(string $objectName, array $objectP
 
             // If it's not an object, then it's an array of similarly named objects, like parameters
             foreach ($property as $subPropIndex => $subProperty) {
+                if (!is_string($subPropIndex)) {
+                    continue;
+                }
                 $lines = array_merge($lines, $this->buildLinesForAnnotationObject($subPropIndex, $subProperty, $indent + 1));
             }
         }
diff --git a/OpenApiDocs.php b/OpenApiDocs.php
@@ -12,6 +12,7 @@
 class OpenApiDocs extends \Piwik\Plugin
 {
     public const DEFAULT_SPEC_VERSION = '1.0.0';
+    public const OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME = 'oaXmlAttributes';
     public const GENERATED_ANNOTATIONS_PATH = '/tmp/annotations/';
     public const EXAMPLE_RESPONSES_PATH = '/tmp/responses/';
     public const GENERATED_SPECS_PATH = '/tmp/specs/';
diff --git a/tests/Unit/AnnotationGeneratorTest.php b/tests/Unit/AnnotationGeneratorTest.php
@@ -914,6 +914,7 @@ public function testBuildSchemaAnnotationFromXmlExample(string $endpoint, array
         $this->assertNotEmpty($normalisedObject, 'The decoded example response should not be empty for endpoint: ' . $endpoint);
         $result = $this->annotationGenerator->buildSchemaAnnotationFromXmlExample($normalisedObject);
         $this->assertEquals(json_encode($expected), json_encode($result), "The XML schema was not as expected for endpoint $endpoint.");
+        $this->assertStringNotContainsString(OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME, json_encode($normalisedObject), "The XML example object should no longer contain the temp attribute property for endpoint $endpoint.");
     }
 
     /**
@@ -937,6 +938,85 @@ public function testBuildPropertyAnnotationFromXmlExample(): void
         $this->expectNotToPerformAssertions();
     }
 
+    /**
+     * @dataProvider getTestDataForTestBuildXmlAttributeSchemaLines
+     *
+     * @param array $attributes
+     * @param array $expected
+     *
+     * @return void
+     */
+    public function testBuildXmlAttributeSchemaLines(array $attributes, array $expected): void
+    {
+        $this->assertEquals($expected, $this->annotationGenerator->buildXmlAttributeSchemaLines($attributes));
+    }
+
+    public static function getTestDataForTestBuildXmlAttributeSchemaLines(): iterable
+    {
+        yield 'should return empty array when attributes are empty' => [[], []];
+        yield 'should return empty array when attributes are nested empty' => [[[]], []];
+        yield 'should return empty array when no attributes have a name' => [[['' => 'value']], []];
+        yield 'should return annotation array as long as the attribute has a name' => [
+            ['testAttribute' => ''],
+            [['@OA\Property' => ['property="testAttribute",', 'type="string",', '@OA\Xml(attribute=true),']]],
+        ];
+        yield 'should return annotation array as long as the attribute has a name even when nested' => [
+            [['testAttribute' => '']],
+            [['@OA\Property' => ['property="testAttribute",', 'type="string",', '@OA\Xml(attribute=true),']]],
+        ];
+        yield 'should return annotation array with example when value is set' => [
+            ['testAttribute' => 'testValue'],
+            [['@OA\Property' => ['property="testAttribute",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue"']]],
+        ];
+        yield 'should return annotation array with example when value is set when nested' => [
+            [['testAttribute' => 'testValue']],
+            [['@OA\Property' => ['property="testAttribute",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue"']]],
+        ];
+        yield 'should return multiple annotation arrays without example when value is not set' => [
+            ['testAttribute1' => '', 'testAttribute2' => ''],
+            [
+                ['@OA\Property' => ['property="testAttribute1",', 'type="string",', '@OA\Xml(attribute=true),']],
+                ['@OA\Property' => ['property="testAttribute2",', 'type="string",', '@OA\Xml(attribute=true),']],
+            ],
+        ];
+        yield 'should return multiple annotation arrays without example when value is not set when nested' => [
+            [['testAttribute1' => ''], ['testAttribute2' => '']],
+            [
+                ['@OA\Property' => ['property="testAttribute1",', 'type="string",', '@OA\Xml(attribute=true),']],
+                ['@OA\Property' => ['property="testAttribute2",', 'type="string",', '@OA\Xml(attribute=true),']],
+            ],
+        ];
+        yield 'should return multiple annotation arrays with example when value is set' => [
+            ['testAttribute1' => 'testValue1', 'testAttribute2' => 'testValue2'],
+            [
+                ['@OA\Property' => ['property="testAttribute1",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue1"']],
+                ['@OA\Property' => ['property="testAttribute2",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue2"']],
+            ],
+        ];
+        yield 'should return multiple annotation arrays with example when value is set when nested' => [
+            [['testAttribute1' => 'testValue1'], ['testAttribute2' => 'testValue2']],
+            [
+                ['@OA\Property' => ['property="testAttribute1",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue1"']],
+                ['@OA\Property' => ['property="testAttribute2",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue2"']],
+            ],
+        ];
+        yield 'should return multiple annotation arrays with example dependent on value' => [
+            ['testAttribute1' => '', 'testAttribute2' => '', 'testAttribute3' => 'testValue3'],
+            [
+                ['@OA\Property' => ['property="testAttribute1",', 'type="string",', '@OA\Xml(attribute=true),']],
+                ['@OA\Property' => ['property="testAttribute2",', 'type="string",', '@OA\Xml(attribute=true),']],
+                ['@OA\Property' => ['property="testAttribute3",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue3"']],
+            ],
+        ];
+        yield 'should return multiple annotation arrays with example dependent on value when nested' => [
+            [['testAttribute1' => 'testValue1'], ['testAttribute2' => '']],
+            [
+                ['@OA\Property' => ['property="testAttribute1",', 'type="string",', '@OA\Xml(attribute=true),', 'example="testValue1"']],
+                ['@OA\Property' => ['property="testAttribute2",', 'type="string",', '@OA\Xml(attribute=true),']],
+            ],
+        ];
+    }
+
     /**
      * @dataProvider getTestDataForRemoveTrailingCommaFromLastLine
      *

Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,7 @@`
`12`	`12`	`class OpenApiDocs extends \Piwik\Plugin`
`13`	`13`	`{`
`14`	`14`	`public const DEFAULT_SPEC_VERSION = '1.0.0';`
	`15`	`+ public const OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME = 'oaXmlAttributes';`
`15`	`16`	`public const GENERATED_ANNOTATIONS_PATH = '/tmp/annotations/';`
`16`	`17`	`public const EXAMPLE_RESPONSES_PATH = '/tmp/responses/';`
`17`	`18`	`public const GENERATED_SPECS_PATH = '/tmp/specs/';`