@oslo-flanders/swagger-generator 2.0.0 → 3.0.1

package/README.md

@@ -24,6 +24,7 @@ The service is executed from the CLI and expects the following parameters:
 | `--input` | The URL or local file path of an OSLO-compliant RDF file | :heavy_check_mark: | |
 | `--output` | The name of the output file | :heavy_check_mark: | |
 | `--language` | The language in which the Swagger must be generated (labels) | No | |
+| `--primaryLanguage` | The primary language of the API. Output files for this language keep their original name, while other languages get a `_{language}` suffix | No | `nl` (default) |
 | `--versionSwagger` | Swagger OpenAPI specification version | :heavy_check_mark: | |
 | `--versionAPI` | API version | :heavy_check_mark: | |
 | `--title` | Title of the API document | :heavy_check_mark: | |

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,16 +128,23 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 ...(Object.keys(links).length > 0 ? { links } : {}),
             },
         };
+        /* Create embedded (self-contained) variant with all $ref resolved inline */
+        const embeddedComponents = this.resolveRefs(components, schemas);
         /* 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 */
+        const languageSuffix = this.configuration.language === this.configuration.primaryLanguage
+            ? ''
+            : `_${this.configuration.language}`;
         for (const format of this.configuration.outputFormat) {
             const ext = (_a = FILE_EXTENSIONS[format]) !== null && _a !== void 0 ? _a : '.json';
             for (const label of Object.keys(schemas))
-                await this.writeOutput(format, schemas[label], `swagger/components/schemas/${label}${ext}`);
+                await this.writeOutput(format, schemas[label], `swagger/components/schemas/${label}${languageSuffix}${ext}`);
             for (const label of Object.keys(links))
-                await this.writeOutput(format, links[label], `swagger/components/links/${label}${ext}`);
-            await this.writeOutput(format, components, `swagger/components${ext}`);
-            await this.writeOutput(format, swagger, `swagger/example${ext}`);
+                await this.writeOutput(format, links[label], `swagger/components/links/${label}${languageSuffix}${ext}`);
+            await this.writeOutput(format, components, `swagger/components${languageSuffix}${ext}`);
+            await this.writeOutput(format, embeddedComponents, `swagger/_embedded${languageSuffix}${ext}`);
+            await this.writeOutput(format, swagger, `swagger/example${languageSuffix}${ext}`);
         }
     }
     createSwagger(schemas, links = {}) {
@@ -592,6 +599,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

@@ -19,6 +19,10 @@ class SwaggerGenerationServiceRunner extends core_1.AppRunner {
         })
             .option('versionAPI', { describe: 'API version.' })
             .option('language', { describe: 'API language tag.', default: 'nl' })
+            .option('primaryLanguage', {
+            describe: 'The primary language of the API. Output files for this language keep their original name, while other languages get a `_{language}` suffix.',
+            default: 'nl',
+        })
             .option('title', {
             describe: 'API title.',
             type: 'string',
@@ -81,6 +85,7 @@ class SwaggerGenerationServiceRunner extends core_1.AppRunner {
             'title',
             'contextURL',
             'baseURL',
+            'language'
         ])
             .help('h')
             .alias('h', 'help');

package/lib/config/SwaggerGenerationServiceConfiguration.d.ts

@@ -13,6 +13,11 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
      * The language of the labels that are used in the context
      */
     private _language;
+    /**
+     * The primary language of the API. Output files for this language keep their
+     * original name, while files for other languages get a `_{language}` suffix.
+     */
+    private _primaryLanguage;
     /**
      * Swagger version
      */
@@ -89,6 +94,7 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
     get input(): string;
     get output(): string;
     get language(): string;
+    get primaryLanguage(): string;
     get versionSwagger(): string;
     get versionAPI(): string;
     get title(): string;

package/lib/config/SwaggerGenerationServiceConfiguration.js

@@ -14,6 +14,7 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
         this._input = params.input;
         this._output = params.output;
         this._language = params.language;
+        this._primaryLanguage = params.primaryLanguage;
         this._versionSwagger = params.versionSwagger;
         this._versionAPI = params.versionAPI;
         this._title = params.title;
@@ -51,6 +52,10 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
         }
         return this._language;
     }
+    get primaryLanguage() {
+        /* Default to Dutch, which is the primary language of the OSLO standards */
+        return this._primaryLanguage || 'nl';
+    }
     get versionSwagger() {
         if (!this._versionSwagger) {
             throw new Error(`Trying to access property "versionSwagger" before it was set.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oslo-flanders/swagger-generator",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "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",