diff --git a/.github/workflows/api_refs.yaml b/.github/workflows/api_refs.yaml index e97d9bb67a..54f5e8c6a9 100644 --- a/.github/workflows/api_refs.yaml +++ b/.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 diff --git a/docs/api/rest_api/rest_api_usage/rest_api_usage.md b/docs/api/rest_api/rest_api_usage/rest_api_usage.md index e53a933ba9..f5081abacb 100644 --- a/docs/api/rest_api/rest_api_usage/rest_api_usage.md +++ b/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](openapi.yaml) +- [JSON format](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 diff --git a/tools/api_refs/api_refs.sh b/tools/api_refs/api_refs.sh index 4d66e342ec..897e1c3f06 100755 --- a/tools/api_refs/api_refs.sh +++ b/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 @@ -37,6 +39,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 +221,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 'Replace download URLs in Redocly config… '; +# Replace version with the base branch +BRANCH_VERSION=$(echo $DXP_VERSION | cut -d '.' -f 1-2); +sed -i.bak "s/\$VERSION/$BRANCH_VERSION/g" $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…'; diff --git a/tools/api_refs/openapi.php b/tools/api_refs/openapi.php index c87f7d3f5d..cd1b09627c 100644 --- a/tools/api_refs/openapi.php +++ b/tools/api_refs/openapi.php @@ -1,24 +1,25 @@ &$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)); diff --git a/tools/api_refs/redocly.yaml b/tools/api_refs/redocly.yaml index 242fe30c16..0d4c112bba 100644 --- a/tools/api_refs/redocly.yaml +++ b/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/$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'