REST API Ref set JSON before XML

Author: adriendupuis

tools/api_refs/api_refs.sh

@@ -18,6 +18,7 @@ PHPDOC_TEMPLATE_VERSION='3.8.0'; # Version of the phpDocumentor base template se
 PHPDOC_DIR="$(pwd)/tools/api_refs/.phpdoc"; # Absolute path to phpDocumentor resource directory (containing the override template set)
 REDOCLY_CONFIG="$(pwd)/tools/api_refs/redocly.yaml"; # Absolute path to Redocly configuration file
 REDOCLY_TEMPLATE="$(pwd)/tools/api_refs/redocly.hbs"; # Absolute path to Redocly wrapping template
+OPENAPI_FIX="$(pwd)/tools/api_refs/openapi.php"; # A script editing and fixing few things on the dumped schema (should be temporary and fixes reported to source)
 
 PHP_BINARY="php -d error_reporting=`php -r 'echo E_ALL & ~E_DEPRECATED;'`"; # Avoid depreciation messages from phpDocumentor/Reflection/issues/529 when using PHP 8.2 or higher
 TMP_DXP_DIR=/tmp/ibexa-dxp-phpdoc; # Absolute path of the temporary directory in which Ibexa DXP will be installed and the PHP API Reference built
@@ -206,6 +207,8 @@ echo 'Dump REST OpenAPI schema… ';
 $PHP_BINARY bin/console ibexa:openapi --yaml \
   | sed "s@info:@info:\n  x-logo:\n    url: 'https://doc.ibexa.co/en/latest/images/ibexa-dxp-logo.png'@" \
 > openapi.yaml;
+echo 'Fix REST OpenAPI schema… ';
+$PHP_BINARY $OPENAPI_FIX;
 echo 'Build REST Reference… ';
 redocly build-docs openapi.yaml --output $REST_API_OUTPUT_FILE --config $REDOCLY_CONFIG --template $REDOCLY_TEMPLATE;
 

tools/api_refs/openapi.php

@@ -0,0 +1,25 @@
+<?php
+
+$openApi = yaml_parse_file('openapi.yaml');
+
+foreach ($openApi['paths'] as $path => &$pathMethods) {
+    foreach ($pathMethods as $method => &$methodDefinition) {
+        if (array_key_exists('requestBody', $methodDefinition) && array_key_exists('content', $methodDefinition['requestBody'])) {
+            //foreach ($methodDefinition['requestBody']['content'] as $contentType => &$contentDefinition) {}
+            ksort($methodDefinition['requestBody']['content']);
+        }/* */elseif (array_key_exists('requestBody', $methodDefinition)) {
+                echo "$method $path\n";
+            }/**/
+        foreach ($methodDefinition['responses'] as $responseCode => &$responseDefinition) {
+            if (array_key_exists('content', $responseDefinition)) {
+                //foreach ($responseDefinition['content'] as $contentType => &$contentDefinition) {}
+                ksort($responseDefinition['content']);
+            }/* * /else {
+                echo "$method $path: $responseCode\n";
+            }/**/
+        }
+    }
+}
+
+yaml_emit_file('openapi.fixed.yaml', $openApi);
+yaml_emit_file('openapi.yaml', $openApi);