zibri 2.4.0 → 2.5.0

package/dist/esm/open-api/open-api.service.js

@@ -11,29 +11,28 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenApiService = void 0;
-const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
+const node_stream_1 = require("node:stream");
 const inject_decorator_1 = require("../di/decorators/inject.decorator");
 const injectable_decorator_1 = require("../di/decorators/injectable.decorator");
 const zibri_di_tokens_default_1 = require("../di/default/zibri-di-tokens.default");
 const inject_function_1 = require("../di/inject.function");
 const relation_enum_1 = require("../entity/models/relation.enum");
 const omit_class_model_1 = require("../entity/omit-class.model");
+const not_found_error_1 = require("../error-handling/errors/not-found.error");
 const global_registry_1 = require("../global/global-registry");
 const http_method_enum_1 = require("../http/http-method.enum");
 const http_status_enum_1 = require("../http/http-status.enum");
 const known_header_enum_1 = require("../http/known-header.enum");
 const mime_type_enum_1 = require("../http/mime-type.enum");
 const file_response_model_1 = require("../parsing/form-data/file-response.model");
+const html_response_model_1 = require("../parsing/html/html-response.model");
 const missing_base_route_error_1 = require("../routing/missing-base-route.error");
 const fs_utilities_1 = require("../utilities/fs.utilities");
-const json_utilities_1 = require("../utilities/json.utilities");
 const metadata_utilities_1 = require("../utilities/metadata.utilities");
 const object_utilities_1 = require("../utilities/object.utilities");
+const sem_ver_utilities_1 = require("../utilities/sem-ver.utilities");
 const defaultDescriptionForHttpStatus = {
     default: 'Response',
     [http_status_enum_1.HttpStatus.INTERNAL_SERVER_ERROR]: 'Internal Server Error',
@@ -82,21 +81,40 @@ let OpenApiService = class OpenApiService {
     assetService;
     authService;
     router;
+    versioningService;
     // eslint-disable-next-line jsdoc/require-jsdoc
     openApiRoute = '/explorer';
-    constructor(logger, assetService, authService, router) {
+    constructor(logger, assetService, authService, router, versioningService) {
         this.logger = logger;
         this.assetService = assetService;
         this.authService = authService;
         this.router = router;
+        this.versioningService = versioningService;
     }
     // eslint-disable-next-line jsdoc/require-jsdoc
     async onAppInit(app) {
-        const definition = await this.createOpenApiDefinition(app);
+        await this.router.registerRoute({
+            httpMethod: http_method_enum_1.HttpMethod.GET,
+            route: `${this.openApiRoute}/spec/:version`,
+            versions: 'all',
+            openApi: { useInOpenApi: false },
+            pathParams: { version: { type: 'string' } },
+            handler: async (req) => {
+                const versionValue = req.params['version'];
+                const versions = this.versioningService.getVersions();
+                const version = versions.find(v => v.value === versionValue);
+                if (!version) {
+                    throw new not_found_error_1.NotFoundError(`Version "${versionValue}" not found`);
+                }
+                return await this.createOpenApiDefinition(app, version);
+            }
+        });
         await this.logger.info(`registers the OpenAPI Explorer at ${this.openApiRoute}`);
         await this.router.registerRoute({
             httpMethod: http_method_enum_1.HttpMethod.GET,
             route: `${this.openApiRoute}/swagger-ui.css`,
+            versions: 'all',
+            openApi: { useInOpenApi: false },
             handler: () => {
                 const filePath = fs_utilities_1.FsUtilities.getPath(this.assetService.publicAssetsPath, 'open-api', 'swagger-ui.css');
                 return file_response_model_1.FileResponse.fromPath(filePath);
@@ -105,6 +123,8 @@ let OpenApiService = class OpenApiService {
         await this.router.registerRoute({
             httpMethod: http_method_enum_1.HttpMethod.GET,
             route: `${this.openApiRoute}/swagger-ui-bundle.js`,
+            versions: 'all',
+            openApi: { useInOpenApi: false },
             handler: () => {
                 const filePath = fs_utilities_1.FsUtilities.getPath(this.assetService.publicAssetsPath, 'open-api', 'swagger-ui-bundle.js');
                 return file_response_model_1.FileResponse.fromPath(filePath);
@@ -113,6 +133,8 @@ let OpenApiService = class OpenApiService {
         await this.router.registerRoute({
             httpMethod: http_method_enum_1.HttpMethod.GET,
             route: `${this.openApiRoute}/swagger-ui-standalone-preset.js`,
+            versions: 'all',
+            openApi: { useInOpenApi: false },
             handler: () => {
                 const filePath = fs_utilities_1.FsUtilities.getPath(this.assetService.publicAssetsPath, 'open-api', 'swagger-ui-standalone-preset.js');
                 return file_response_model_1.FileResponse.fromPath(filePath);
@@ -121,158 +143,244 @@ let OpenApiService = class OpenApiService {
         await this.router.registerRoute({
             httpMethod: http_method_enum_1.HttpMethod.GET,
             route: `${this.openApiRoute}/swagger-ui-init.js`,
-            handler: (_, res) => {
-                res.type('.js').send([
-                    'window.onload = function() {',
-                    '    SwaggerUIBundle({',
-                    `        spec: ${json_utilities_1.JsonUtilities.stringify(definition)},`,
-                    '        dom_id: \'#swagger-ui\',',
-                    '        presets: [',
-                    '            SwaggerUIBundle.presets.apis,',
-                    '            SwaggerUIStandalonePreset',
-                    '        ],',
-                    '        layout: "StandaloneLayout",',
-                    '        requestInterceptor: (req) => {',
-                    '            req.headers.Accept = \'application/json\'',
-                    `            req.headers['${known_header_enum_1.KnownHeader.CONTENT_TYPE}'] = \'application/json\'`,
-                    '            return req;',
-                    '        },',
-                    '        defaultModelRendering: \'model\'',
-                    '    });',
-                    '};'
-                ].join('\n'));
+            versions: 'all',
+            openApi: { useInOpenApi: false },
+            handler: () => {
+                const formatDate = (0, inject_function_1.inject)(zibri_di_tokens_default_1.ZIBRI_DI_TOKENS.FORMAT_DATE);
+                const versions = this.versioningService
+                    .getVersions()
+                    .sort((a, b) => sem_ver_utilities_1.SemVerUtilities.compare(a.value, b.value) === 'bigger' ? -1 : 1);
+                // eslint-disable-next-line jsdoc/require-jsdoc
+                const urls = versions.map(v => ({
+                    url: `${this.openApiRoute}/spec/${v.value}`,
+                    name: v.endsAt == undefined
+                        ? `${v.value} (latest)`
+                        : `${v.value} (${formatDate(v.startsAt)} - ${formatDate(v.endsAt)})`
+                }));
+                const latestVersion = versions.find(v => v.endsAt == undefined);
+                return file_response_model_1.FileResponse.fromStream({
+                    filename: 'swagger-ui-init.js',
+                    mimeType: mime_type_enum_1.MimeType.JAVASCRIPT,
+                    stream: node_stream_1.Readable.from([
+                        [
+                            'window.onload = function() {',
+                            '    window.ui = SwaggerUIBundle({',
+                            `        urls: ${JSON.stringify(urls)},`,
+                            `        "urls.primaryName": "${latestVersion?.value ?? ''}",`,
+                            '        dom_id: \'#swagger-ui\',',
+                            '        presets: [',
+                            '            SwaggerUIBundle.presets.apis,',
+                            '            SwaggerUIStandalonePreset',
+                            '        ],',
+                            '        layout: "StandaloneLayout",',
+                            '        requestInterceptor: (req) => {',
+                            '            req.headers.Accept = \'application/json\'',
+                            `            req.headers['${known_header_enum_1.KnownHeader.CONTENT_TYPE}'] = \'application/json\'`,
+                            '            return req;',
+                            '        },',
+                            '        defaultModelRendering: \'model\'',
+                            '    });',
+                            '};'
+                        ].join('\n')
+                    ])
+                });
             }
         });
         await this.router.registerRoute({
             httpMethod: http_method_enum_1.HttpMethod.GET,
             route: `${this.openApiRoute}/custom.js`,
-            handler: (_, res) => {
-                res.type('.js').send([
-                    '(function waitForTopbar() {',
-                    '    const topbar = document.querySelector(\'.information-container\');',
-                    '    if (!topbar) {',
-                    '        return setTimeout(waitForTopbar, 50);',
-                    '    }',
-                    '    if (document.getElementById(\'zibri-openapi-logo\')) {',
-                    '        return;',
-                    '    }',
-                    '',
-                    '    const a = document.createElement(\'a\');',
-                    '    a.id = \'zibri-openapi-logo\';',
-                    '    a.href = \'/\';',
-                    '',
-                    '    const img = document.createElement(\'img\');',
-                    `    img.src = '${this.assetService.assetsRoute}/logo.jpg';`,
-                    '    img.height = 100;',
-                    '    img.width = 100;',
-                    '',
-                    '    a.appendChild(img);',
-                    `    a.append('${global_registry_1.GlobalRegistry.getAppData('name')}')`,
-                    '    topbar.insertBefore(a, topbar.firstChild);',
-                    '})();',
-                    '',
-                    '(function waitForSwagger() {',
-                    '    if (!window.ui || typeof window.ui.specSelectors !== \'object\') {',
-                    '        return setTimeout(waitForSwagger, 50);',
-                    '    }',
-                    // eslint-disable-next-line stylistic/max-len
-                    '    const spec = window.ui.specSelectors.specJson().toJS ? window.ui.specSelectors.specJson().toJS() : window.ui.specSelectors.specJson();',
-                    '    if (!spec || !spec.paths) {',
-                    '        return setTimeout(waitForSwagger, 50);',
-                    '    }',
-                    '',
-                    '    function normalizeMethod(m) {',
-                    '        return String(m).toLowerCase();',
-                    '    }',
-                    '',
-                    // eslint-disable-next-line cspell/spellchecker
-                    '    const opblocks = Array.from(document.querySelectorAll(\'.opblock\'));',
-                    // eslint-disable-next-line cspell/spellchecker
-                    '    opblocks.forEach((op) => {',
-                    '        try {',
-                    // eslint-disable-next-line cspell/spellchecker
-                    '            const methodEl = op.querySelector(\'.opblock-summary-method\');',
-                    // eslint-disable-next-line cspell/spellchecker
-                    '            const pathEl = op.querySelector(\'.opblock-summary-path\');',
-                    '            if (!methodEl || !pathEl) {',
-                    '                return;',
-                    '            }',
-                    '            const method = normalizeMethod(methodEl.textContent?.trim() ?? \'\');',
-                    '            const path = (pathEl.textContent?.trim() ?? \'\');',
-                    '',
-                    '            const pathObj = spec.paths && spec.paths[path];',
-                    '            if (!pathObj) {',
-                    '                return;',
-                    '            }',
-                    '            const operationObj = pathObj[method];',
-                    '            if (!operationObj) {',
-                    '                return;',
-                    '            }',
-                    '            const roles = operationObj[\'x-roles\'];',
-                    '            if (!roles || !Array.isArray(roles) || roles.length === 0) {',
-                    '                return;',
-                    '            }',
-                    '',
-                    '            if (op.querySelector(\'.zibri-roles-container\')) {',
-                    '                return;',
-                    '            }',
-                    '            const container = document.createElement(\'div\');',
-                    '            container.className = \'zibri-roles-container\';',
-                    '            container.setAttribute(\'aria-hidden\', \'true\');',
-                    '',
-                    '            roles.forEach((r) => {',
-                    '                const badge = document.createElement(\'span\');',
-                    '                badge.className = \'zibri-role-badge\';',
-                    '                badge.textContent = String(r);',
-                    '                container.appendChild(badge);',
-                    '            });',
-                    '',
-                    // eslint-disable-next-line cspell/spellchecker
-                    '            const summary = op.querySelector(\'.opblock-summary-path-description-wrapper\');',
-                    '            summary.appendChild(container);',
-                    // '            if (summary) {',
-                    // '                const lock = summary.querySelector(\'.authorization__btn\');',
-                    // '                if (lock) {',
-                    // '                    summary.insertBefore(container, lock);',
-                    // '                } else {',
-                    // '                    summary.appendChild(container);',
-                    // '                }',
-                    // '            }',
-                    '        } catch (e) {',
-                    '            console.warn(\'zibri openapi role injection failed\', e);',
-                    '        }',
-                    '    });',
-                    '})();'
-                ].join('\n'));
+            versions: 'all',
+            openApi: { useInOpenApi: false },
+            handler: () => {
+                return file_response_model_1.FileResponse.fromStream({
+                    filename: 'custom.js',
+                    mimeType: mime_type_enum_1.MimeType.JAVASCRIPT,
+                    stream: node_stream_1.Readable.from([
+                        [
+                            '(function() {',
+                            '    function injectLogo(topbar) {',
+                            '        if (topbar.querySelector(\'#zibri-openapi-logo\')) {',
+                            '            return;',
+                            '        }',
+                            '        const a = document.createElement(\'a\');',
+                            '        a.id = \'zibri-openapi-logo\';',
+                            '        a.href = \'/\';',
+                            '',
+                            '        const img = document.createElement(\'img\');',
+                            `        img.src = '${this.assetService.assetsRoute}/logo.jpg';`,
+                            '        img.height = 100;',
+                            '        img.width = 100;',
+                            '',
+                            '        a.appendChild(img);',
+                            `        a.append('${global_registry_1.GlobalRegistry.getAppData('name')}');`,
+                            '        topbar.insertBefore(a, topbar.firstChild);',
+                            '    }',
+                            '',
+                            '    function observe() {',
+                            '        const topbar = document.querySelector(\'.information-container\');',
+                            '        if (!topbar) {',
+                            '            setTimeout(observe, 50);',
+                            '            return;',
+                            '        }',
+                            '        injectLogo(topbar);',
+                            '        new MutationObserver(() => {',
+                            '            const t = document.querySelector(\'.information-container\');',
+                            '            if (t) {',
+                            '                injectLogo(t);',
+                            '            }',
+                            '        }).observe(document.body, { childList: true, subtree: true });',
+                            '    }',
+                            '',
+                            '    observe();',
+                            '})();',
+                            '',
+                            '(function() {',
+                            '    let isInjecting = false;',
+                            '',
+                            '    function injectRoles() {',
+                            '        if (isInjecting) return;',
+                            '        if (!window.ui || typeof window.ui.specSelectors !== \'object\') return;',
+                            '',
+                            '        const spec = window.ui.specSelectors.specJson().toJS',
+                            '            ? window.ui.specSelectors.specJson().toJS()',
+                            '            : window.ui.specSelectors.specJson();',
+                            '',
+                            '        if (!spec || !spec.paths) return;',
+                            '',
+                            '        isInjecting = true;',
+                            '        try {',
+                            '            const normalizeMethod = (m) => String(m).toLowerCase();',
+                            '',
+                            // eslint-disable-next-line cspell/spellchecker
+                            '            const opBlocks = document.querySelectorAll(\'.opblock\');',
+                            '            opBlocks.forEach((op) => {',
+                            '                try {',
+                            // eslint-disable-next-line cspell/spellchecker
+                            '                    const methodEl = op.querySelector(\'.opblock-summary-method\');',
+                            // eslint-disable-next-line cspell/spellchecker
+                            '                    const pathEl = op.querySelector(\'.opblock-summary-path\');',
+                            '                    if (!methodEl || !pathEl) return;',
+                            '',
+                            '                    const method = normalizeMethod(methodEl.textContent.trim());',
+                            '                    const path = pathEl.textContent.trim();',
+                            '',
+                            '                    const pathObj = spec.paths[path];',
+                            '                    if (!pathObj) return;',
+                            '',
+                            '                    const operationObj = pathObj[method];',
+                            '                    if (!operationObj) return;',
+                            '',
+                            '                    const roles = operationObj[\'x-roles\'];',
+                            '                    if (!roles || !Array.isArray(roles) || roles.length === 0) return;',
+                            '',
+                            '                    if (op.querySelector(\'.zibri-roles-container\')) return;',
+                            '',
+                            '                    const container = document.createElement(\'div\');',
+                            '                    container.className = \'zibri-roles-container\';',
+                            '                    container.setAttribute(\'aria-hidden\', \'true\');',
+                            '',
+                            '                    roles.forEach((r) => {',
+                            '                        const badge = document.createElement(\'span\');',
+                            '                        badge.className = \'zibri-role-badge\';',
+                            '                        badge.textContent = String(r);',
+                            '                        container.appendChild(badge);',
+                            '                    });',
+                            '',
+                            // eslint-disable-next-line cspell/spellchecker
+                            '                    const summary = op.querySelector(\'.opblock-summary-path-description-wrapper\');',
+                            '                    if (summary) summary.appendChild(container);',
+                            '                } catch (e) {',
+                            '                    console.warn(\'zibri openapi role injection failed\', e);',
+                            '                }',
+                            '            });',
+                            '        } finally {',
+                            '            isInjecting = false;',
+                            '        }',
+                            '    }',
+                            '',
+                            '    function waitForSwaggerAndObserve() {',
+                            '        if (!window.ui || typeof window.ui.specSelectors !== \'object\') {',
+                            '            return setTimeout(waitForSwaggerAndObserve, 50);',
+                            '        }',
+                            '',
+                            '        const spec = window.ui.specSelectors.specJson().toJS',
+                            '            ? window.ui.specSelectors.specJson().toJS()',
+                            '            : window.ui.specSelectors.specJson();',
+                            '',
+                            '        if (!spec || !spec.paths) {',
+                            '            return setTimeout(waitForSwaggerAndObserve, 50);',
+                            '        }',
+                            '',
+                            '        // Initial injection',
+                            '        injectRoles();',
+                            '',
+                            '        // Watch for version switches / re-renders',
+                            '        const swaggerContainer = document.getElementById(\'swagger-ui\');',
+                            '        if (!swaggerContainer) return;',
+                            '',
+                            '        let debounceTimer;',
+                            '        const observer = new MutationObserver(() => {',
+                            '            clearTimeout(debounceTimer);',
+                            '            debounceTimer = setTimeout(() => {',
+                            '                injectRoles();',
+                            '            }, 200);',
+                            '        });',
+                            '',
+                            '        observer.observe(swaggerContainer, { childList: true, subtree: true });',
+                            '    }',
+                            '',
+                            '    waitForSwaggerAndObserve();',
+                            '})();'
+                        ].join('\n')
+                    ])
+                });
             }
         });
-        app.use(this.openApiRoute, swagger_ui_express_1.default.serve);
         await this.router.registerRoute({
             httpMethod: http_method_enum_1.HttpMethod.GET,
             route: this.openApiRoute,
-            handler: swagger_ui_express_1.default.setup(definition, {
-                // eslint-disable-next-line cspell/spellchecker
-                customfavIcon: `${this.assetService.assetsRoute}/favicon.png`,
-                customSiteTitle: definition.info.title,
-                customCssUrl: `${this.assetService.assetsRoute}/open-api/custom.css`,
-                customJs: `${this.openApiRoute}/custom.js`
-            })
+            versions: 'all',
+            openApi: { useInOpenApi: false },
+            handler: () => {
+                return html_response_model_1.HtmlResponse.fromString(`<!DOCTYPE html>
+                    <html lang="en">
+                    <head>
+                        <meta charset="UTF-8">
+                        <title>${global_registry_1.GlobalRegistry.getAppData('name')} | Explorer</title>
+                        <link rel="stylesheet" href="${this.openApiRoute}/swagger-ui.css">
+                        <link rel="icon" href="${this.assetService.assetsRoute}/favicon.png">
+                        <link rel="stylesheet" href="${this.assetService.assetsRoute}/open-api/custom.css">
+                    </head>
+                    <body>
+                        <div id="swagger-ui"></div>
+                        <script src="${this.openApiRoute}/swagger-ui-bundle.js"></script>
+                        <script src="${this.openApiRoute}/swagger-ui-standalone-preset.js"></script>
+                        <script src="${this.openApiRoute}/swagger-ui-init.js"></script>
+                        <script src="${this.openApiRoute}/custom.js"></script>
+                    </body>
+                    </html>`, {
+                    csp: {
+                        styleSrc: ['\'self\'', '\'unsafe-hashes\'', '\'sha256-RL3ie0nH+Lzz2YNqQN83mnU0J1ot4QL7b99vMdIX99w=\''],
+                        imgSrc: ['\'self\'', 'data:']
+                    }
+                });
+            }
         });
     }
     // eslint-disable-next-line jsdoc/require-jsdoc
-    async createOpenApiDefinition(app) {
+    async createOpenApiDefinition(app, version) {
         const tags = app.options.controllers.map(cls => ({ name: cls.name }));
         const res = {
             openapi: '3.1.0',
             info: {
                 title: `${global_registry_1.GlobalRegistry.getAppData('name')} | Explorer`,
-                version: global_registry_1.GlobalRegistry.getAppData('version') ?? '0.0.0'
+                version: version.value
             },
             tags,
             components: {
                 securitySchemes: this.resolveSecuritySchemes()
             },
-            paths: await this.resolveOpenApiPaths(app)
+            paths: await this.resolveOpenApiPaths(app, version)
         };
         return res;
     }
@@ -283,15 +391,20 @@ let OpenApiService = class OpenApiService {
         }
         return res;
     }
-    async resolveOpenApiPaths(app) {
+    // eslint-disable-next-line sonar/cognitive-complexity
+    async resolveOpenApiPaths(app, version) {
         const res = {};
-        for (const controllerClass of app.options.controllers) {
+        for (const controllerClass of app.options.controllers.sort((a, b) => a.name.localeCompare(b.name))) {
             const controllerData = metadata_utilities_1.MetadataUtilities.getControllerData(controllerClass);
             if (!controllerData) {
                 throw new missing_base_route_error_1.MissingBaseRouteError(controllerClass);
             }
             const routes = metadata_utilities_1.MetadataUtilities.getControllerRoutes(controllerClass);
             for (const route of routes) {
+                const routeVersions = route.versions ?? controllerData.versions;
+                if (!this.versioningService.matchesVersion(routeVersions, version)) {
+                    continue;
+                }
                 const pathParams = metadata_utilities_1.MetadataUtilities.getRoutePathParams(controllerClass, route.controllerMethod);
                 const queryParams = metadata_utilities_1.MetadataUtilities.getRouteQueryParams(controllerClass, route.controllerMethod);
                 const headerParams = metadata_utilities_1.MetadataUtilities.getRouteHeaderParams(controllerClass, route.controllerMethod);
@@ -318,6 +431,9 @@ let OpenApiService = class OpenApiService {
             }
         }
         for (const route of this.router.manuallyRegisteredRoutes.filter(r => r.openApi.useInOpenApi)) {
+            if (!this.versioningService.matchesVersion(route.versions, version)) {
+                continue;
+            }
             // Ensure an entry exists
             const fullPath = `${route.route}`.replaceAll(/:([^/]+)/g, '{$1}');
             res[fullPath] ??= {};
@@ -393,7 +509,7 @@ let OpenApiService = class OpenApiService {
                     return undefined;
                 }
                 const propMeta = metadata_utilities_1.MetadataUtilities.getModelProperties(response.cls);
-                const schema = this.buildOpenApiSchemaForProperties(propMeta, response.cls, 'response');
+                const schema = this.buildOpenApiSchemaForProperties(propMeta, response.cls, 'response', new Set());
                 if (response.isArray === true) {
                     return { [mime_type_enum_1.MimeType.JSON]: { schema: { type: 'array', items: schema } } };
                 }
@@ -431,7 +547,7 @@ let OpenApiService = class OpenApiService {
                         continue;
                     }
                     const propMeta = metadata_utilities_1.MetadataUtilities.getModelProperties(response.cls);
-                    const schema = this.buildOpenApiSchemaForProperties(propMeta, response.cls, 'response');
+                    const schema = this.buildOpenApiSchemaForProperties(propMeta, response.cls, 'response', new Set());
                     if (response.isArray === true) {
                         schemas.push({ type: 'array', items: schema });
                         continue;
@@ -466,7 +582,7 @@ let OpenApiService = class OpenApiService {
             return undefined;
         }
         const propMeta = metadata_utilities_1.MetadataUtilities.getModelProperties(metadata.modelClass);
-        const schema = this.buildOpenApiSchemaForProperties(propMeta, metadata.modelClass, 'request');
+        const schema = this.buildOpenApiSchemaForProperties(propMeta, metadata.modelClass, 'request', new Set());
         return {
             required: typeof metadata.required === 'boolean' ? metadata.required : undefined,
             description: metadata.description,
@@ -474,7 +590,14 @@ let OpenApiService = class OpenApiService {
         };
     }
     // eslint-disable-next-line sonar/cognitive-complexity
-    buildOpenApiSchemaForProperties(propMeta, entity, context) {
+    buildOpenApiSchemaForProperties(propMeta, entity, context, visited) {
+        // ---- cycle guard ----
+        if (visited.has(entity)) {
+            // Return a stub schema (or a ref if you later extract components).
+            // Returning an empty object is safe, but a description helps debugging.
+            return { type: 'object', description: 'Circular reference omitted' };
+        }
+        visited.add(entity);
         const properties = {};
         const required = [];
         for (const [key, meta] of object_utilities_1.ObjectUtilities.entries(propMeta)) {
@@ -527,17 +650,18 @@ let OpenApiService = class OpenApiService {
                 case 'object': {
                     const objectPropMeta = metadata_utilities_1.MetadataUtilities.getModelProperties(meta.cls());
                     properties[key] = {
-                        ...this.buildOpenApiSchemaForProperties(objectPropMeta, entity, context),
+                        ...this.buildOpenApiSchemaForProperties(objectPropMeta, entity, context, visited),
                         description: meta.description
                     };
                     continue;
                 }
-                case relation_enum_1.Relation.ONE_TO_ONE:
+                case relation_enum_1.Relation.HAS_ONE:
+                case relation_enum_1.Relation.BELONGS_TO_ONE:
                 case relation_enum_1.Relation.MANY_TO_ONE: {
                     const targetClass = this.getTargetClassForRelation(meta, entity);
                     const objectPropMeta = metadata_utilities_1.MetadataUtilities.getModelProperties(targetClass);
                     properties[key] = {
-                        ...this.buildOpenApiSchemaForProperties(objectPropMeta, entity, context),
+                        ...this.buildOpenApiSchemaForProperties(objectPropMeta, entity, context, visited),
                         description: meta.description
                     };
                     continue;
@@ -555,7 +679,7 @@ let OpenApiService = class OpenApiService {
                             exclude: false,
                             allowAdditionalProperties: false
                         }
-                    }, entity, context);
+                    }, entity, context, visited);
                     properties[key] = {
                         type: 'array',
                         description: meta.description,
@@ -567,7 +691,7 @@ let OpenApiService = class OpenApiService {
                     if (meta.items.type === 'object') {
                         entity = meta.items.cls();
                     }
-                    const items = this.buildOpenApiSchemaForProperties({ items: meta.items }, entity, context);
+                    const items = this.buildOpenApiSchemaForProperties({ items: meta.items }, entity, context, visited);
                     properties[key] = {
                         type: 'array',
                         description: meta.description,
@@ -601,7 +725,8 @@ let OpenApiService = class OpenApiService {
         const properties = metadata_utilities_1.MetadataUtilities.getModelProperties(fullTargetClass);
         for (const key in properties) {
             const property = properties[key];
-            if (property.type !== relation_enum_1.Relation.ONE_TO_ONE
+            if (property.type !== relation_enum_1.Relation.BELONGS_TO_ONE
+                && property.type !== relation_enum_1.Relation.HAS_ONE
                 && property.type !== relation_enum_1.Relation.ONE_TO_MANY
                 && property.type !== relation_enum_1.Relation.MANY_TO_ONE
                 && property.type !== relation_enum_1.Relation.MANY_TO_MANY) {
@@ -663,7 +788,7 @@ let OpenApiService = class OpenApiService {
                 const propMeta = metadata_utilities_1.MetadataUtilities.getModelProperties(meta.cls());
                 return {
                     description: meta.description,
-                    ...this.buildOpenApiSchemaForProperties(propMeta, meta.cls(), 'request')
+                    ...this.buildOpenApiSchemaForProperties(propMeta, meta.cls(), 'request', new Set())
                 };
             }
             case 'array': {
@@ -683,6 +808,7 @@ exports.OpenApiService = OpenApiService = __decorate([
     __param(1, (0, inject_decorator_1.Inject)(zibri_di_tokens_default_1.ZIBRI_DI_TOKENS.ASSET_SERVICE)),
     __param(2, (0, inject_decorator_1.Inject)(zibri_di_tokens_default_1.ZIBRI_DI_TOKENS.AUTH_SERVICE)),
     __param(3, (0, inject_decorator_1.Inject)(zibri_di_tokens_default_1.ZIBRI_DI_TOKENS.ROUTER)),
-    __metadata("design:paramtypes", [Object, Object, Object, Object])
+    __param(4, (0, inject_decorator_1.Inject)(zibri_di_tokens_default_1.ZIBRI_DI_TOKENS.VERSIONING_SERVICE)),
+    __metadata("design:paramtypes", [Object, Object, Object, Object, Object])
 ], OpenApiService);
 //# sourceMappingURL=open-api.service.js.map