@oslo-flanders/swagger-generator 3.0.0 → 3.1.0

package/lib/SwaggerGenerationService.d.ts

@@ -17,4 +17,12 @@ export declare class SwaggerGenerationService implements IService {
     createSchemas(): Object;
     createLinks(): Object;
     writeOutput(outputFormat: OutputFormat, obj: Object, outputPath: string): Promise<void>;
+    /**
+     * Create a self-contained copy of the components object where all `$ref`
+     * pointers to `#/components/schemas/<name>` are replaced by the actual
+     * schema definition inline. Resolves recursively so that nested `$ref`
+     * references are also inlined. Circular references are preserved as `$ref`
+     * to avoid infinite recursion.
+     */
+    private resolveRefs;
 }

package/lib/SwaggerGenerationService.js

@@ -128,6 +128,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 ...(Object.keys(links).length > 0 ? { links } : {}),
             },
         };
+        /* Create embedded (self-contained) variant with all $ref resolved inline */
+        const embeddedComponents = this.configuration.generateEmbedded
+            ? this.resolveRefs(components, schemas)
+            : undefined;
         /* Create Swagger endpoint paths as example */
         const swagger = this.createSwagger(schemas, links);
         /* Only append the language suffix when the generated language differs from the primary language */
@@ -141,6 +145,9 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             for (const label of Object.keys(links))
                 await this.writeOutput(format, links[label], `swagger/components/links/${label}${languageSuffix}${ext}`);
             await this.writeOutput(format, components, `swagger/components${languageSuffix}${ext}`);
+            if (embeddedComponents) {
+                await this.writeOutput(format, embeddedComponents, `swagger/_embedded${languageSuffix}${ext}`);
+            }
             await this.writeOutput(format, swagger, `swagger/example${languageSuffix}${ext}`);
         }
     }
@@ -596,6 +603,71 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         (0, core_1.ensureOutputDirectory)(path.dirname(filePath));
         await (0, promises_1.writeFile)(filePath, data);
     }
+    /**
+     * Create a self-contained copy of the components object where all `$ref`
+     * pointers to `#/components/schemas/<name>` are replaced by the actual
+     * schema definition inline. Resolves recursively so that nested `$ref`
+     * references are also inlined. Circular references are preserved as `$ref`
+     * to avoid infinite recursion.
+     */
+    resolveRefs(components, schemas) {
+        const embedded = JSON.parse(JSON.stringify(components));
+        const resolving = new Set();
+        function walk(obj) {
+            if (!obj || typeof obj !== 'object') {
+                return;
+            }
+            if (Array.isArray(obj)) {
+                for (let i = 0; i < obj.length; i++) {
+                    if (obj[i] !== null && typeof obj[i] === 'object' && obj[i].$ref) {
+                        const match = obj[i].$ref.match(/^#\/components\/schemas\/(.+)$/);
+                        if (match && schemas[match[1]]) {
+                            if (resolving.has(match[1])) {
+                                // Circular reference – keep the $ref as-is
+                                continue;
+                            }
+                            resolving.add(match[1]);
+                            obj[i] = JSON.parse(JSON.stringify(schemas[match[1]]));
+                            walk(obj[i]);
+                            resolving.delete(match[1]);
+                        }
+                    }
+                    else {
+                        walk(obj[i]);
+                    }
+                }
+            }
+            else {
+                for (const key of Object.keys(obj)) {
+                    if (key === '$ref' &&
+                        typeof obj[key] === 'string' &&
+                        obj.$ref.startsWith('#/components/schemas/')) {
+                        continue;
+                    }
+                    if (obj[key] !== null &&
+                        typeof obj[key] === 'object' &&
+                        obj[key].$ref) {
+                        const match = obj[key].$ref.match(/^#\/components\/schemas\/(.+)$/);
+                        if (match && schemas[match[1]]) {
+                            if (resolving.has(match[1])) {
+                                // Circular reference – keep the $ref as-is
+                                continue;
+                            }
+                            resolving.add(match[1]);
+                            obj[key] = JSON.parse(JSON.stringify(schemas[match[1]]));
+                            walk(obj[key]);
+                            resolving.delete(match[1]);
+                        }
+                    }
+                    else {
+                        walk(obj[key]);
+                    }
+                }
+            }
+        }
+        walk(embedded);
+        return embedded;
+    }
 };
 SwaggerGenerationService = __decorate([
     (0, inversify_1.injectable)(),

package/lib/SwaggerGenerationServiceRunner.js

@@ -50,6 +50,11 @@ class SwaggerGenerationServiceRunner extends core_1.AppRunner {
             describe: 'Disable the creation of links.',
             default: false,
             boolean: true,
+        })
+            .option('generateEmbedded', {
+            describe: 'Generate the embedded (self-contained) variant with all $ref resolved inline.',
+            default: false,
+            boolean: true,
         })
             .option('expanded', {
             describe: 'Use JSON-LD expanded format instead of default compact format.',

package/lib/config/SwaggerGenerationServiceConfiguration.d.ts

@@ -78,6 +78,10 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
      * Whether to disable the creation of links
      */
     private _disableLinks;
+    /**
+     * Whether to generate the embedded (self-contained) variant with all $ref resolved inline
+     */
+    private _generateEmbedded;
     /**
      * Whether to use expanded JSON-LD format or not
      */
@@ -110,6 +114,7 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
     get excludeProperties(): string[];
     get outputFormat(): OutputFormat[];
     get disableLinks(): boolean;
+    get generateEmbedded(): boolean;
     get expanded(): boolean;
     get excludeClassesExpanded(): string[];
     get excludePropertiesExpanded(): string[];

package/lib/config/SwaggerGenerationServiceConfiguration.js

@@ -30,6 +30,7 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
         this._excludeProperties = params.excludeProperties;
         this._outputFormat = params.outputFormat;
         this._disableLinks = params.disableLinks;
+        this._generateEmbedded = params.generateEmbedded;
         this._expanded = params.expanded;
         this._excludeClassesExpanded = params.excludeClassesExpanded;
         this._excludePropertiesExpanded = (params.excludePropertiesExpanded);
@@ -116,6 +117,9 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
     get disableLinks() {
         return !!this._disableLinks;
     }
+    get generateEmbedded() {
+        return !!this._generateEmbedded;
+    }
     get expanded() {
         return !!this._expanded;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oslo-flanders/swagger-generator",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Generate OpenAPI Swagger YAML documentation.",
   "author": "Digitaal Vlaanderen <https://data.vlaanderen.be/id/organisatie/OVO002949>",
   "homepage": "https://github.com/informatievlaanderen/OSLO-UML-Transformer/tree/main/packages/oslo-generator-swagger#readme",