Update API Refs

Author: adriendupuis

tools/api_refs/README.md

@@ -6,45 +6,45 @@ Requires [`jq`](https://stedolan.github.io/jq/download/)
 
 ## Basic usage
 
-`tools/php_api_ref/phpdoc.sh` is a script generating PHP API Reference, by default, under `docs/api/php_api/php_api_reference/`.
+`tools/api_refs/api_refs.sh` is a script generating PHP API Reference, by default, under `docs/api/php_api/php_api_reference/`.
 
 - For Composer, if you do not use a global authentication to retrieve _Commerce_ edition, a path to an auth.json file can be given as first argument. For example:
   ```
-  tools/php_api_ref/phpdoc.sh ~/www/ibexa-dxp-commerce/auth.json
+  tools/api_refs/api_refs.sh ~/www/ibexa-dxp-commerce/auth.json
   ```
 - The second argument can be a path to an output directory to use instead of the default one. For example, using the Composer global authentication file as first argument and the path to directory (which is created if it doesn't exist yet):
   ```
-  tools/php_api_ref/phpdoc.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
+  tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
   ```
 
 ## Rebuild example
 
 ```bash
-tools/php_api_ref/phpdoc.sh
+tools/api_refs/api_refs.sh
 git add docs/api/php_api/php_api_reference/
 git commit -m "Rebuild PHP API Ref's HTML"
 git push
 ```
 
 ## Maintenance
 
-In `tools/php_api_ref/phpdoc.sh`:
+In `tools/api_refs/api_refs.sh`:
 
 `PHPDOC_VERSION` should always target the last version of phpDocumentor.
 
 `DXP_VERSION` should target the version of Ibexa DXP Commerce corresponding to the main doc's branch.
 
 ### Templates
 
-Custom templates are located in `tools/php_api_ref/.phpdoc/template/` directory.
+Custom templates are located in `tools/api_refs/.phpdoc/template/` directory.
 They are overriding the default templates from a phpDocumentor version.
 The default templates version is not always the same as the phpDocumentor binary version.
 To update the default templates version, the overriding custom templates must be updated as well to obtain a better or equal result without bug.
 See `PHPDOC_VERSION` and `PHPDOC_TEMPLATE_VERSION`.
 
 ## Advanced usage
 
-`tools/php_api_ref/phpdoc.sh` has a set of internal variables that might be edited for particular usages.
+`tools/api_refs/api_refs.sh` has a set of internal variables that might be edited for particular usages.
 
 `PHPDOC_CONF` can be changed to use a different config file.
 For example, when working on the design, the set of parsed files can be reduced for a quicker PHP API Reference compilation.
@@ -58,16 +58,16 @@ Time is saved. The DXP's code could even be modified for test purpose.
 If you change some of those values, please do not commit those changes, and don't commit their output.
 To prevent that, you can make a local copy, and use this copy to generate in a temporary output directory:
 ```shell
-cp tools/php_api_ref/phpdoc.sh tools/php_api_ref/phpdoc.dev.sh
+cp tools/api_refs/api_refs.sh tools/api_refs/phpdoc.dev.sh
 nano phpdoc.dev.sh # Edit and make your changes. For example, change PHPDOC_CONF to use phpdoc.dev.xml.
 nano phpdoc.dev.xml # Edit and make your changes. For example, target only your package.
-tools/php_api_ref/phpdoc.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
+tools/api_refs/api_refs.sh ~/.composer/auth.json ./docs/api/php_api/php_api_reference-TMP
 ```
 
 ### Test a branch
 
 To load a package on a development branch instead of a released version,
-uncommented in `phpdoc.sh` the piece of code about `MY_PACKAGE` and `MY_BRANCH`,
+uncommented in `api_refs.sh` the piece of code about `MY_PACKAGE` and `MY_BRANCH`,
 and set the value of those two variables.
 
 `MY_PACKAGE` is the name of the Ibexa package without the vendor.

tools/api_refs/api_refs.sh

@@ -3,35 +3,40 @@
 set +x;
 
 AUTH_JSON=${1:-~/.composer/auth.json}; # Path to an auth.json file allowing to install the targeted edition and version
-OUTPUT_DIR=${2:-./docs/api/php_api/php_api_reference}; # Path to the directory where the built PHP API Reference is hosted
+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
 
 DXP_EDITION='commerce'; # Edition from and for which the Reference is built
-DXP_VERSION='5.0.x-dev'; # Version from and for which the Reference is built
+DXP_VERSION='5.0.0-rc1'; # Version from and for which the Reference is built
 DXP_ADD_ONS=(automated-translation rector); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
 DXP_EDITIONS=(oss headless experience commerce); # Available editions ordered by ascending capabilities
 SF_VERSION='7.2'; # Symfony version used by Ibexa DXP
 PHPDOC_VERSION='3.8.0'; # Version of phpDocumentor used to build the Reference
-PHPDOC_CONF="$(pwd)/tools/php_api_ref/phpdoc.dist.xml"; # Absolute path to phpDocumentor configuration file
-#PHPDOC_CONF="$(pwd)/tools/php_api_ref/phpdoc.dev.xml"; # Absolute path to phpDocumentor configuration file
+PHPDOC_CONF="$(pwd)/tools/api_refs/phpdoc.dist.xml"; # Absolute path to phpDocumentor configuration file
+#PHPDOC_CONF="$(pwd)/tools/api_refs/phpdoc.dev.xml"; # Absolute path to phpDocumentor configuration file
 PHPDOC_TEMPLATE_VERSION='3.8.0'; # Version of the phpDocumentor base template set
-PHPDOC_DIR="$(pwd)/tools/php_api_ref/.phpdoc"; # Absolute path to phpDocumentor resource directory (containing the override 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_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
 FORCE_DXP_INSTALL=1; # If 1, empty the temporary directory, install DXP from scratch, build, remove temporary directory; if 0, potentially reuse the DXP already installed in temporary directory, keep temporary directory for future uses.
-BASE_DXP_BRANCH='master'; # Branch from and for which the Reference is built when using a dev branch as version
-VIRTUAL_DXP_VERSION='5.0.0'; # Version for which the reference is supposedly built when using dev branch as version
+BASE_DXP_BRANCH=''; # Branch from and for which the Reference is built when using a dev branch as version
+VIRTUAL_DXP_VERSION=''; # Version for which the reference is supposedly built when using dev branch as version
 
-if [ ! -d $OUTPUT_DIR ]; then
-  echo -n "Creating ${OUTPUT_DIR}… ";
-  mkdir -p $OUTPUT_DIR;
+if [ ! -d $PHP_API_OUTPUT_DIR ]; then
+  echo -n "Creating ${PHP_API_OUTPUT_DIR}… ";
+  mkdir -p $PHP_API_OUTPUT_DIR;
   if [ $? -eq 0 ]; then
     echo 'OK';
   else
     exit 1;
   fi;
 fi;
-OUTPUT_DIR=$(realpath $OUTPUT_DIR); # Transform to absolute path before changing the working directory
+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
 
 if [ 1 -eq $FORCE_DXP_INSTALL ]; then
   echo 'Remove temporary directory…';
@@ -59,6 +64,13 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
     fi;
     composer config repositories.ibexa composer https://updates.ibexa.co;
     composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
+  elif [[ "$DXP_VERSION" == *"-rc"* ]]; then
+    composer create-project ibexa/website-skeleton:$DXP_VERSION . --no-interaction --ignore-platform-reqs --no-scripts --stability=rc;
+    if [ -n "$AUTH_JSON" ]; then
+      cp $AUTH_JSON ./;
+    fi;
+    composer config repositories.ibexa composer https://updates.ibexa.co;
+    composer require ibexa/$DXP_EDITION:$DXP_VERSION --no-interaction --update-with-all-dependencies --no-install --ignore-platform-reqs --no-scripts;
   else
     composer create-project ibexa/$DXP_EDITION-skeleton:$DXP_VERSION . --no-interaction --no-install --ignore-platform-reqs --no-scripts;
     if [ -n "$AUTH_JSON" ]; then
@@ -179,21 +191,36 @@ if [ $? -eq 0 ]; then
     ./php_api_reference/js/searchIndex.js \
     > ./php_api_reference/js/searchIndex.new.js;
   mv -f ./php_api_reference/js/searchIndex.new.js ./php_api_reference/js/searchIndex.js;
-  echo -n "Copy phpDocumentor output to ${OUTPUT_DIR}… ";
-  cp -rf ./php_api_reference/* $OUTPUT_DIR;
+  echo -n "Copy phpDocumentor output to ${PHP_API_OUTPUT_DIR}… ";
+  cp -rf ./php_api_reference/* $PHP_API_OUTPUT_DIR;
   echo -n 'Remove surplus… ';
   while IFS= read -r line; do
     file="$(echo $line | sed -r 's/Only in (.*): (.*)/\1\/\2/')";
-    if [[ $file = $OUTPUT_DIR/* ]]; then
+    if [[ $file = $PHP_API_OUTPUT_DIR/* ]]; then
       rm -rf $file;
     fi;
-  done <<< "$(diff -qr ./php_api_reference $OUTPUT_DIR | grep 'Only in ')";
+  done <<< "$(diff -qr ./php_api_reference $PHP_API_OUTPUT_DIR | grep 'Only in ')";
   echo 'OK.';
 else
-  echo 'A phpDocumentor error prevents reference update.';
+  echo 'A phpDocumentor error prevents PHP Reference update.';
   exit 3;
 fi;
 
+if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
+  echo 'Set up DXP recipes…';
+  git init && git add . && git commit -m "Installed Ibexa Commerce" > /dev/null;
+  composer recipes:install ibexa/$DXP_EDITION --force --reset --no-interaction;
+fi;
+
+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;
+
 if [ 1 -eq $FORCE_DXP_INSTALL ]; then
   echo 'Remove temporary directory…';
   rm -rf $TMP_DXP_DIR;

tools/api_refs/openapi.php

@@ -0,0 +1,24 @@
+<?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.yaml', $openApi);

tools/api_refs/redocly.hbs

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf8" />
+  <title>{{title}}</title>
+  <!-- needed for adaptive design -->
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="icon" href="https://doc.ibexa.co/en/latest/images/favicon.png" />
+  <style>
+    body {
+      padding: 0;
+      margin: 0;
+    }
+  </style>
+  {{{redocHead}}}
+  {{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
+</head>
+
+<body>
+  {{{redocHTML}}}
+  <script>
+    window.addEventListener('load', () => {
+      window.setTimeout(() => {
+        let logo = document.querySelector('img[src$="ibexa-dxp-logo.png"]');
+        logo.onclick = () => {
+          let pathParts = document.location.pathname.split('/').slice(0, 3);
+          document.location = pathParts.join('/') + '/api/rest_api/rest_api_usage/rest_api_usage/';
+        };
+        logo.setAttribute('style', 'cursor: pointer; margin: 13px;');
+      }, 500);
+    });
+  </script>
+</body>
+
+</html>

tools/api_refs/redocly.yaml

@@ -0,0 +1,7 @@
+theme:
+  openapi:
+    hideHostname: true
+    theme:
+      logo:
+        maxWidth: '76px!important'
+        maxHeight: '26px'