REST API Reference: version OpenAPI specification in the repo

.github/workflows/api_refs.yaml

@@ -27,7 +27,7 @@ jobs:
             - name: Checkout documentation
               uses: actions/checkout@v4
               with:
-                  ref: ${{ steps.version_and_branches.outputs.base_branch }}
+                  ref: openapi-file
 
             - name: Disable PHP coverage
               uses: shivammathur/setup-php@v2
@@ -43,7 +43,7 @@ jobs:
               env:
                   SATIS_NETWORK_KEY: ${{ secrets.SATIS_NETWORK_KEY }}
                   SATIS_NETWORK_TOKEN: ${{ secrets.SATIS_NETWORK_TOKEN }}
-                  BASE_BRANCH: ${{ steps.version_and_branches.outputs.base_branch }}
+                  BASE_BRANCH: openapi-file
               run: |
                   composer config --global http-basic.updates.ibexa.co $SATIS_NETWORK_KEY $SATIS_NETWORK_TOKEN
                   if [[ '4.6' != $BASE_BRANCH ]]; then
@@ -73,6 +73,9 @@ jobs:
                   git diff-index --quiet --cached HEAD || git commit -m "PHP API Ref HTML"
                   git add docs/api/rest_api/rest_api_reference/rest_api_reference.html
                   git diff-index --quiet --cached HEAD || git commit -m "REST API Ref HTML"
+                  git add docs/api/rest_api/rest_api_reference/openapi.yaml
+                  git add docs/api/rest_api/rest_api_reference/openapi.json
+                  git diff-index --quiet --cached HEAD || git commit -m "REST API OpenAPI spec"
 
             - name: Create Pull Request
               uses: peter-evans/create-pull-request@v7

docs/api/rest_api/rest_api_usage/rest_api_usage.md

@@ -15,7 +15,12 @@ The REST API uses HTTP methods (such as `GET` and `PUBLISH`), and HTTP headers t
 
 The REST API is built on top of [API Platform](https://api-platform.com/docs/symfony/) and meets the [OpenAPI](https://www.openapis.org/) standard.
 
-You can download the OpenAPI specification from the [REST API Reference](/api/rest_api/rest_api_reference/rest_api_reference.html), or generate it for your project by running one of the commands below: 
+You can download the OpenAPI specification in:
+
+- [YAML format](/api/rest_api/rest_api_reference/openapi.yaml)
+- [JSON format](/api/rest_api/rest_api_reference/openapi.json)
+
+You can also generate one for your project by running one of the commands below:
 
 ``` bash
 php bin/console ibexa:openapi --output=openapi.json # JSON output

tools/api_refs/api_refs.sh

@@ -5,6 +5,8 @@ set +x;
 AUTH_JSON=${1:-~/.composer/auth.json}; # Path to an auth.json file allowing to install the targeted edition and version
 PHP_API_OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory where the built PHP API Reference is hosted
 REST_API_OUTPUT_FILE=${3:-./docs/api/rest_api/rest_api_reference/rest_api_reference.html}; # Path to the REST API Reference file
+REST_API_OPENAPI_FILE_YAML=${4:-./docs/api/rest_api/rest_api_reference/openapi.yaml}; # Path to the REST API OpenAPI spec file
+REST_API_OPENAPI_FILE_JSON=${5:-./docs/api/rest_api/rest_api_reference/openapi.json}; # Path to the REST API OpenAPI spec file
 
 DXP_EDITION='commerce'; # Edition from and for which the Reference is built
 DXP_VERSION='5.0.*'; # Version from and for which the Reference is built
@@ -16,7 +18,8 @@ PHPDOC_CONF="$(pwd)/tools/api_refs/phpdoc.dist.xml"; # Absolute path to phpDocum
 #PHPDOC_CONF="$(pwd)/tools/api_refs/phpdoc.dev.xml"; # Absolute path to phpDocumentor configuration file
 PHPDOC_TEMPLATE_VERSION='3.9.1'; # Version of the phpDocumentor base template set
 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_CONFIG_TEMPLATE="$(pwd)/tools/api_refs/redocly.yaml.template"; # Absolute path to Redocly configuration template file
+REDOCLY_CONFIG="$(pwd)/tools/api_refs/redocly.yaml"; # Absolute path to Redocly configuration file (generated from template)
 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)
 
@@ -37,6 +40,8 @@ if [ ! -d $PHP_API_OUTPUT_DIR ]; then
 fi;
 PHP_API_OUTPUT_DIR=$(realpath $PHP_API_OUTPUT_DIR); # Transform into absolute path before changing the working directory
 REST_API_OUTPUT_FILE=$(realpath $REST_API_OUTPUT_FILE); # Transform into absolute path before changing the working directory
+REST_API_OPENAPI_FILE_YAML=$(realpath $REST_API_OPENAPI_FILE_YAML); # Transform into absolute path before changing the working directory
+REST_API_OPENAPI_FILE_JSON=$(realpath $REST_API_OPENAPI_FILE_JSON); # Transform into absolute path before changing the working directory
 
 if [ 1 -eq $FORCE_DXP_INSTALL ]; then
   echo 'Remove temporary directory…';
@@ -217,10 +222,20 @@ 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;
+$PHP_BINARY bin/console ibexa:openapi \
+  | sed 's@"info": {@"info": {\n    "x-logo": {\n      "url": "https://doc.ibexa.co/en/latest/images/ibexa-dxp-logo.png"\n    },@' \
+> openapi.json;
 echo 'Fix REST OpenAPI schema… ';
 $PHP_BINARY $OPENAPI_FIX;
 echo 'Build REST Reference… ';
+echo 'Generate Redocly config from template… ';
+# Replace version with the base branch
+BRANCH_VERSION=$(echo $DXP_VERSION | cut -d '.' -f 1-2);
+sed "s/\$VERSION/$BRANCH_VERSION/g" $REDOCLY_CONFIG_TEMPLATE > $REDOCLY_CONFIG;
 redocly build-docs openapi.yaml --output $REST_API_OUTPUT_FILE --config $REDOCLY_CONFIG --template $REDOCLY_TEMPLATE;
+echo 'Copy OpenAPI spec to documentation… ';
+cp openapi.yaml $REST_API_OPENAPI_FILE_YAML;
+cp openapi.json $REST_API_OPENAPI_FILE_JSON;
 
 if [ 1 -eq $FORCE_DXP_INSTALL ]; then
   echo 'Remove temporary directory…';

tools/api_refs/openapi.php

@@ -1,24 +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";
-            }/**/
+function sortOpenApiContent(array &$openApi): void
+{
+    foreach ($openApi['paths'] as $path => &$pathMethods) {
+        foreach ($pathMethods as $method => &$methodDefinition) {
+            if (array_key_exists('requestBody', $methodDefinition) && array_key_exists('content', $methodDefinition['requestBody'])) {
+                ksort($methodDefinition['requestBody']['content']);
+            }
+            foreach ($methodDefinition['responses'] as $responseCode => &$responseDefinition) {
+                if (array_key_exists('content', $responseDefinition)) {
+                    ksort($responseDefinition['content']);
+                }
+            }
         }
     }
 }
 
+$openApi = yaml_parse_file('openapi.yaml');
+sortOpenApiContent($openApi);
 yaml_emit_file('openapi.yaml', $openApi);
+
+$openApiJson = json_decode(file_get_contents('openapi.json'), true);
+sortOpenApiContent($openApiJson);
+file_put_contents('openapi.json', json_encode($openApiJson, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));

tools/api_refs/redocly.yaml

@@ -4,3 +4,8 @@ openapi:
     logo:
       maxWidth: '76px!important'
       maxHeight: '26px'
+  downloadUrls:
+    - title: Download as YAML
+      url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/test/docs/api/rest_api/rest_api_reference/openapi.yaml'
+    - title: Download as JSON
+      url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/test/docs/api/rest_api/rest_api_reference/openapi.json'

tools/api_refs/redocly.yaml.template

@@ -0,0 +1,11 @@
+openapi:
+  hideHostname: true
+  theme:
+    logo:
+      maxWidth: '76px!important'
+      maxHeight: '26px'
+  downloadUrls:
+    - title: Download as YAML
+      url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/$VERSION/docs/api/rest_api/rest_api_reference/openapi.yaml'
+    - title: Download as JSON
+      url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/$VERSION/docs/api/rest_api/rest_api_reference/openapi.json'