Skip to content

REST API reference for SaaS #3419

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mnocon merged 6 commits into from
Sep 30, 2026
Merged

REST API reference for SaaS #3419

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4f0cb2d
REST API reference for SaaS
mnocon Sep 25, 2026
b602f7e
Changed title. Removed corporate account schema
mnocon Sep 25, 2026
bad6fcf
Reworked approach
mnocon Sep 29, 2026
9a92f7e
Fixed logo
mnocon Sep 29, 2026
d587983
Removed sorting of responses and requests
mnocon Sep 30, 2026
42c1b23
REST API Reference v6.0.x-dev (#3430)
ezrobot Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/api_refs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ on:
type: boolean
default: false
base_branch:
description: 'Start from this branch of the doc to build the refs (default: Maj.min from version)'
description: 'Start from this branch of the doc to build the refs (default: saas)'
required: false
type: string
work_branch:
Expand Down Expand Up @@ -50,7 +50,7 @@ jobs:
version="${version#v}"
base_branch="$INPUT_BASE_BRANCH"
if [ -z "$base_branch" ]; then
base_branch="$(echo "$version" | sed 's/\(.*\..*\)\..*/\1/')"
base_branch="saas"
fi
work_branch="$INPUT_WORK_BRANCH"
if [ -z "$work_branch" ]; then
Expand Down
94,096 changes: 39,640 additions & 54,456 deletions docs/api/rest_api/rest_api_reference/openapi.json
View file
Open in desktop

Large diffs are not rendered by default.

76,391 changes: 31,301 additions & 45,090 deletions docs/api/rest_api/rest_api_reference/openapi.yaml
View file
Open in desktop

Large diffs are not rendered by default.

9,541 changes: 5,102 additions & 4,439 deletions docs/api/rest_api/rest_api_reference/rest_api_reference.html
View file
Open in desktop

Large diffs are not rendered by default.

29 changes: 24 additions & 5 deletions tools/api_refs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,25 @@ Requires [`jq`](https://stedolan.github.io/jq/download/) and the [Redocly CLI](h
by default, under `docs/api/rest_api/rest_api_reference/`.

It installs a temporary Ibexa DXP, dumps its OpenAPI schema with `bin/console ibexa:openapi`,
fixes the dumped schema with `tools/api_refs/openapi.php`, and renders the reference with Redocly.
fixes the dumped schema with `tools/api_refs/openapi.php`, adapts it to SaaS with `redocly bundle`,
and renders the reference with Redocly.

- 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 optional argument. For example:
The reference documents Ibexa DXP SaaS:

- It's built from the _Experience_ edition and the add-ons listed in `DXP_ADD_ONS`.
The build fails if a package listed in `DXP_FORBIDDEN_PACKAGES`, for example a _Commerce_ one, gets installed.
- The decorators in `tools/api_refs/redocly.yaml` adapt the OpenAPI specification to SaaS:
- `info-override` sets the title and the logo, and empties the version so that it isn't displayed.
- `filter-out` removes the groups (tags) unavailable on SaaS, for example Corporate Account, and their endpoints.
- `saas/remove-badges` removes the edition badges (`x-badges`). The build fails if any badge remains.
- `saas/remove-unused-tags` removes the tags left without endpoints, so that they aren't displayed as empty groups.
- `remove-unused-components` removes the schemas no longer used.

`saas/*` decorators are defined in `tools/api_refs/redocly-saas-plugin.js`.
Decorators are applied by `redocly bundle` only, not by `redocly build-docs`, which is why the reference is built from the bundled specification.
- The build fails if Redocly fails.

- For Composer, if you do not use a global authentication to retrieve _Experience_ edition, a path to an auth.json file can be given as first optional argument. For example:
```
tools/api_refs/api_refs.sh ~/www/ibexa-dxp-commerce/auth.json
```
Expand All @@ -36,14 +52,17 @@ git push

In `tools/api_refs/api_refs.sh`:

`DXP_VERSION` should target the version of Ibexa DXP Commerce corresponding to the doc's branch.
`DXP_VERSION` should target the version of Ibexa DXP Experience corresponding to SaaS.

`DXP_ADD_ONS` lists the packages installed on top of the edition so that their REST endpoints are dumped.

`DXP_FORBIDDEN_PACKAGES` lists the packages unavailable on SaaS which mustn't be pulled in by the edition or the add-ons.

### Templates

The reference is rendered by Redocly from `tools/api_refs/redocly.hbs`,
configured by `tools/api_refs/redocly.yaml`, which is generated from `tools/api_refs/redocly.yaml.template`.
configured by `tools/api_refs/redocly.yaml`.
Its download links point to the OpenAPI specification files on the `saas` branch.

## Advanced usage

Expand Down Expand Up @@ -130,7 +149,7 @@ gh workflow run api_refs.yaml -f version=<tag> -f use_dev_version=<false|true> -
`-f version=<tag>` to pass the Ibexa DXP version tag for which the API Reference is built.
`-f use_dev_version=<false|true>` to use the released version designed by the tag, or to use the development version (`v5.0.x-dev`) for an incoming tag.
`--ref <branch>` to use the `api_refs.yaml` workflow from a given branch instead of the default branch (`5.0`).
`-f base_branch=<branch>` to use the `api_refs.sh` from a given branch and make a PR to that branch.
`-f base_branch=<branch>` to use the `api_refs.sh` from a given branch and make a PR to that branch (default: `saas`).
`-f work_branch=<branch>` to use a given target branch to commit the build and make a PR from that branch.
`-f force=<false|true>` to force the commit on the target branch even if it already exists.

Expand Down
55 changes: 34 additions & 21 deletions tools/api_refs/api_refs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,12 @@ REST_API_OUTPUT_FILE=${2:-./docs/api/rest_api/rest_api_reference/rest_api_refere
REST_API_OPENAPI_FILE_YAML=${3:-./docs/api/rest_api/rest_api_reference/openapi.yaml}; # Path to the REST API OpenAPI spec file
REST_API_OPENAPI_FILE_JSON=${4:-./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_EDITION='experience'; # Edition from and for which the Reference is built; SaaS runs Experience
DXP_VERSION="${DXP_VERSION:-6.0.*}"; # Version from and for which the Reference is built; can be overridden by the DXP_VERSION env var (e.g. v5.0.x-dev for a dev build)
DXP_ADD_ONS=(integrated-help fieldtype-richtext-rte connector-anthropic connector-gemini shopping-list cdp connector-raptor connector-quable mcp); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
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)
DXP_ADD_ONS=(cdp connector-raptor connector-quable mcp); # Packages not included in $DXP_EDITION but added to the Reference, listed without their vendor "ibexa"
DXP_FORBIDDEN_PACKAGES=(commerce cart checkout order-management payment shipping discounts discounts-codes shopping-list); # Commerce packages which must not be installed, as SaaS doesn't provide them, listed without their vendor "ibexa"
REDOCLY_CONFIG="$(pwd)/tools/api_refs/redocly.yaml"; # Absolute path to Redocly configuration file, including the decorators adapting the schema to SaaS
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 deprecation messages from the Symfony console when using PHP 8.2 or higher
COMPOSER_BINARY='composer';
Expand Down Expand Up @@ -87,34 +86,48 @@ if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
done;
fi;

echo 'Check that no Commerce package is installed…';
for forbidden_package in "${DXP_FORBIDDEN_PACKAGES[@]}"; do
if $COMPOSER_BINARY -n show ibexa/$forbidden_package > /dev/null 2>&1; then
echo "Package ibexa/${forbidden_package} is installed but isn't available on SaaS. Check which package requires it with: composer why ibexa/${forbidden_package}";
exit 4;
fi;
done;

if [[ "$DXP_VERSION" == *".x-dev" ]]; then
DXP_VERSION=$VIRTUAL_DXP_VERSION;
fi;

if [ 0 -eq $DXP_ALREADY_EXISTS ]; then
echo 'Set up DXP recipes…';
git init -b main && git add . && git commit -m "Installed Ibexa Commerce" > /dev/null;
git init -b main && git add . && git commit -m "Installed Ibexa $DXP_EDITION" > /dev/null;
$COMPOSER_BINARY 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/saas/images/cohesivo-logo.png'@" \
> openapi.yaml;
$PHP_BINARY bin/console ibexa:openapi \
| sed 's@"info": {@"info": {\n "x-logo": {\n "url": "https://doc.ibexa.co/en/saas/images/cohesivo-logo.png"\n },@' \
> openapi.json;
echo 'Fix REST OpenAPI schema… ';
$PHP_BINARY $OPENAPI_FIX;
$PHP_BINARY bin/console ibexa:openapi --yaml > openapi.yaml;
echo 'Adapt REST OpenAPI schema to SaaS… ';
mkdir -p saas;
for extension in yaml json; do
redocly bundle openapi.yaml --config $REDOCLY_CONFIG --output saas/openapi.$extension;
if [ $? -ne 0 ]; then
echo "Redocly failed to bundle the OpenAPI schema as ${extension}.";
exit 7;
fi;
done;
if grep -q 'x-badges' saas/openapi.yaml saas/openapi.json; then
echo 'Badges remain in the OpenAPI schema after adapting it.';
exit 5;
fi;
echo 'Build REST Reference… ';
echo 'Generate Redocly config from template… ';
# Replace version with the base branch
BRANCH_VERSION=$(echo $DXP_VERSION | sed 's/^v*\([^v.]*\.[^.]*\).*/\1/');
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;
redocly build-docs saas/openapi.yaml --output $REST_API_OUTPUT_FILE --config $REDOCLY_CONFIG --template $REDOCLY_TEMPLATE;
if [ $? -ne 0 ]; then
echo 'Redocly failed to build the REST Reference.';
exit 6;
fi;
echo 'Copy OpenAPI spec to documentation… ';
cp openapi.yaml $REST_API_OPENAPI_FILE_YAML;
cp openapi.json $REST_API_OPENAPI_FILE_JSON;
cp saas/openapi.yaml $REST_API_OPENAPI_FILE_YAML;
cp saas/openapi.json $REST_API_OPENAPI_FILE_JSON;

if [ 1 -eq $FORCE_DXP_INSTALL ]; then
echo 'Remove temporary directory…';
Expand Down
25 changes: 0 additions & 25 deletions tools/api_refs/openapi.php
View file
Open in desktop

This file was deleted.

37 changes: 37 additions & 0 deletions tools/api_refs/redocly-saas-plugin.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
// Redocly decorators adapting the dumped OpenAPI schema to SaaS, complementing the built-in ones configured in redocly.yaml.
module.exports = function saasPlugin() {
return {
id: 'saas',
decorators: {
oas3: {
// Edition badges are meaningless on SaaS.
'remove-badges': () => ({
Operation: {
leave(operation) {
delete operation['x-badges'];
},
},
}),
// Tags left without operations by filter-out would still be displayed as empty groups.
'remove-unused-tags': () => {
const usedTags = new Set();

return {
Operation: {
leave(operation) {
(operation.tags || []).forEach((tag) => usedTags.add(tag));
},
},
Root: {
leave(root) {
if (root.tags) {
root.tags = root.tags.filter((tag) => usedTags.has(tag.name));
}
},
},
};
},
},
},
};
};
15 changes: 0 additions & 15 deletions tools/api_refs/redocly.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,21 +69,6 @@
<script>
window.addEventListener('load', () => {
window.setTimeout(() => {
// Remove badges from TOC
document.querySelectorAll('.menu-content [role="menuitem"] [type="badge"]').forEach(el => el.remove());

// Apply badge styling
document.querySelectorAll('.api-content [data-section-id] h2 [type="primary"]').forEach(el => {
const color = el.getAttribute('color');
el.style.backgroundColor = "#FFF";
el.style.border = "1px solid " + color;
el.style.padding = "1px 8px";
el.style.marginRight = "8px";
el.style.color = color;
el.style.fontWeight = "initial";
el.style.borderRadius = "0px";
});

let logo = document.querySelector('img[src$="cohesivo-logo-alt.svg"]');
logo.onclick = () => {
let pathParts = document.location.pathname.split('/').slice(0, 3);
Expand Down
21 changes: 19 additions & 2 deletions tools/api_refs/redocly.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,23 @@ openapi:
maxHeight: '32px'
downloadUrls:
- title: Download as YAML
url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/6.0/docs/api/rest_api/rest_api_reference/openapi.yaml'
url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/saas/docs/api/rest_api/rest_api_reference/openapi.yaml'
- title: Download as JSON
url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/6.0/docs/api/rest_api/rest_api_reference/openapi.json'
url: 'https://raw.githubusercontent.com/ibexa/documentation-developer/saas/docs/api/rest_api/rest_api_reference/openapi.json'
plugins:
- ./redocly-saas-plugin.js
# Applied by `redocly bundle` only, not by `redocly build-docs`: api_refs.sh bundles the schema before building the reference from it.
decorators:
info-override:
title: Cohesivo SaaS REST API
# Empty so that the version isn't displayed next to the title.
version: ''
x-logo:
url: 'https://doc.ibexa.co/en/saas/images/cohesivo-logo-alt.svg'
# Groups not available on SaaS.
filter-out:
property: tags
value: ['Corporate Account', 'Url Wildcard', 'User Token']
saas/remove-badges: on
saas/remove-unused-tags: on
remove-unused-components: on
Comment on lines +47 to +49

@mnocon mnocon Sep 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

About this, Claude says the following:

Both are needed only because of filter-out. Neither is doing anything for the endpoints you keep. I measured this on the saas spec (202 paths, 546 schemas, 42 tags).

saas/remove-unused-tags: needed.
- On the original spec it removes nothing, because all 42 tags have endpoints.
- After filter-out, exactly three tags are left with no endpoints: Url Wildcard, User Token and Corporate Account.
- filter-out only removes the endpoints, not the tag definitions. I checked earlier that without this decorator Redoc still shows the three as empty groups in the sidebar.

remove-unused-components: not needed for the HTML, only for the YAML and JSON downloads.
- Redoc renders only the schemas that endpoints reference. The config and template have no schema-definitions section, so leftover schemas never show on the page.
- Without it, the downloadable specs keep the 32 schemas that only the removed endpoints used, such as Company, Member, the URL wildcard schemas and the JWT token schemas. Anyone reading the files would still see Corporate Account and the other removed features.
- It also drops 11 schemas that were already unused before filtering: CartProduct, CartQuery, ContentCreateContentType, ContentMetadataUpdate, Country, CountryList, CountryListWrapper, LanguageCode, ProductContentUpdate, UserGroupUnassign, VersionTranslationInfo. Nothing references them, so removing them changes nothing visible. The two Cart ones are left over from Commerce, and the Experience build may not contain them anyway.

I'd keep both. If you're fine with the downloads still containing schemas for the removed groups, you can drop remove-unused-components. If you ever drop filter-out, both become unnecessary.

32 changes: 0 additions & 32 deletions tools/api_refs/redocly.yaml.template
View file
Open in desktop

This file was deleted.

Loading