@oslo-flanders/swagger-generator 1.0.4 → 1.1.1

package/README.md

@@ -3,12 +3,15 @@
 > Given an OSLO-compliant RDF file, this tool generates a Swagger API from it.
 
 ## Install
+
 ```bash
 npm install @oslo-flanders/swagger-generator
 ```
 
 ## Global install
+
 To use the service from the command line anywhere, you can install it globally.
+
 ```bash
 npm install -g @oslo-flanders/swagger-generator
 ```
@@ -16,25 +19,31 @@ npm install -g @oslo-flanders/swagger-generator
 ## API
 
 The service is executed from the CLI and expects the following parameters:
-| Parameter          | Description                                                  | Required           | Possible values             |
+| Parameter | Description | Required | Possible values |
 | ------------------ | ------------------------------------------------------------ | ------------------ | --------------------------- |
-| `--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                 |                             |
-| `--versionSwagger` | Swagger OpenAPI specification version                        | :heavy_check_mark: |                             |
-| `--versionAPI`     | API version                                                  | :heavy_check_mark: |                             |
-| `--title`          | Title of the API document                                    | :heavy_check_mark: |                             |
-| `--description`    | Description of the API document                              | :heavy_check_mark: |                             |
-| `--contextURL`     | JSON-LD context URL of the datastandard used in the API      | :heavy_check_mark: |                             |
-| `--baseURL`        | API base URL for endpoints and PURIs                         | :heavy_check_mark: |                             |
-| `--contactName`    | Name of the person or organisation to contact about the API  | No                 |                             |
-| `--contactEmail`   | E-mail to contact for questions about the API                | No                 |                             |
-| `--contactURL`     | Link to follow as contact about the API                      | No                 |                             |
-| `--licenseName`    | Name of the license of the API                               | No                 |                             |
-| `--licenseURL`     | URL of the license of the API                                | No                 |                             |
-| `--silent`         | Suppress log messages                                        | No                 | `true` or `false` (default) |
+| `--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 | |
+| `--versionSwagger` | Swagger OpenAPI specification version | :heavy_check_mark: | |
+| `--versionAPI` | API version | :heavy_check_mark: | |
+| `--title` | Title of the API document | :heavy_check_mark: | |
+| `--description` | Description of the API document | :heavy_check_mark: | |
+| `--contextURL` | JSON-LD context URL of the datastandard used in the API | :heavy_check_mark: | |
+| `--baseURL` | API base URL for endpoints and PURIs | :heavy_check_mark: | |
+| `--contactName` | Name of the person or organisation to contact about the API | No | |
+| `--contactEmail` | E-mail to contact for questions about the API | No | |
+| `--contactURL` | Link to follow as contact about the API | No | |
+| `--licenseName` | Name of the license of the API | No | |
+| `--licenseURL` | URL of the license of the API | No | |
+| `--excludeClasses` | Classes to exclude from the generated Swagger | No | Persoon Organisatie Test |
+| `--excludeProperties` | Properties to exclude from the generated Swagger | No | voornaam achternaam |
+| `--silent` | Suppress log messages | No | `true` or `false` (default) |
 
 ## Usage
+
 ```bash
 oslo-generator-swagger --input report.jsonld --output swagger.json --language nl --versionSwagger 3.0.4 --versionAPI 1.0.0 --title "Mijn API" --description "Mijn API beschrijving." --contextURL http://example.com/context.jsonld --baseURL http://example.com
+oslo-generator-swagger --input report.jsonld --output swagger.json --language nl --versionSwagger 3.0.4 --versionAPI 1.0.0 --title "Mijn API" --description "Mijn API beschrijving." --contextURL http://example.com/context.jsonld --baseURL http://example.com --excludeClasses Persoon Organisatie
+oslo-generator-swagger --input report.jsonld --output swagger.json --language nl --versionSwagger 3.0.4 --versionAPI 1.0.0 --title "Mijn API" --description "Mijn API beschrijving." --contextURL http://example.com/context.jsonld --baseURL http://example.com --excludeClasses Persoon --excludeProperties Persoon.voornaam
+oslo-generator-swagger --input report.jsonld --output swagger.json --language nl --versionSwagger 3.0.4 --versionAPI 1.0.0 --title "Mijn API" --description "Mijn API beschrijving." --contextURL http://example.com/context.jsonld --baseURL http://example.com --excludeClasses GeregistreerdPersoon --excludeProperties Persoon.voornaam Persoon.achternaam
 ```

package/lib/SwaggerGenerationService.js

@@ -152,6 +152,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             }
             /* Class labels should be always pascal cased */
             label = (0, core_1.toPascalCase)(label);
+            /* If a class is excluded via configuration, stop here */
+            if (this.configuration.excludeClasses.includes(label)) {
+                continue;
+            }
             /* Only keep links which are related to the class */
             for (const key of Object.keys(links)) {
                 if (key.startsWith(`${label}.`))
@@ -294,6 +298,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             }
             /* Class labels should be always pascal cased */
             label = (0, core_1.toPascalCase)(label);
+            /* If a class is excluded via configuration, stop here */
+            if (this.configuration.excludeClasses.includes(label)) {
+                continue;
+            }
             attributes[label] = [];
             requiredAttributes[label] = [];
             /* Find all attributes for object */
@@ -311,6 +319,11 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 }
                 /* Attribute labels should be always camel cased */
                 attributeLabel = (0, core_1.toCamelCase)(attributeLabel);
+                // Addition for the `excludeProperties` flag to remove any reference to an excluded property
+                const classNameWithPropertyName = `${label}.${attributeLabel}`;
+                if (this.configuration.excludeProperties.includes(classNameWithPropertyName)) {
+                    continue;
+                }
                 if (!attributeRangeId) {
                     this.logger.error(`Unknown range for attribute ${attributeId.value}`);
                     continue;
@@ -344,7 +357,11 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 }
                 /* Arrays must be introduced into the schema if the max cardinality is 2 or more */
                 const description = `${attributeDefinition}${attributeUsageNote ? ' ' + attributeUsageNote : ''}`;
-                const properties = (0, Properties_1.mapProperties)(attributeDatatypeId, attributeDatatypeLabel, subclasses, attributeDatatypeAbstract);
+                const properties = (0, Properties_1.mapProperties)(attributeDatatypeId, attributeDatatypeLabel, subclasses, attributeDatatypeAbstract, this.configuration.excludeClasses);
+                // If mapProperties returns nothing, the property pointed to an excluded class (this.configuration.excludeClasses)
+                if (!properties) {
+                    continue;
+                }
                 const requiredProperties = properties
                     ? Object.keys(properties)
                     : undefined;
@@ -437,6 +454,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             }
             /* Class labels should be always pascal cased */
             label = (0, core_1.toPascalCase)(label);
+            /* If a class is excluded via configuration, stop here */
+            if (this.configuration.excludeClasses.includes(label)) {
+                continue;
+            }
             /* Find all attributes for object */
             for (const attributeId of attributeIds) {
                 let attributeLabel = (_b = (0, core_1.getApplicationProfileLabel)(attributeId, this.store, this.configuration.language)) === null || _b === void 0 ? void 0 : _b.value;
@@ -447,6 +468,11 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 }
                 /* Attribute labels should be always camel cased */
                 attributeLabel = (0, core_1.toCamelCase)(attributeLabel);
+                // Addition for the `excludeProperties` flag to remove any reference to an excluded property
+                const classNameWithPropertyName = `${label}.${attributeLabel}`;
+                if (this.configuration.excludeProperties.includes(classNameWithPropertyName)) {
+                    continue;
+                }
                 if (!attributeRangeId) {
                     this.logger.error(`Unknown range for attribute ${attributeId.value}`);
                     continue;
@@ -458,6 +484,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                     continue;
                 }
                 attributeDatatypeLabel = (0, core_1.toPascalCase)(attributeDatatypeLabel);
+                // Addition for the `excludeClasses` flag to remove any reference to an excluded class
+                if (this.configuration.excludeClasses.includes(attributeDatatypeLabel)) {
+                    continue;
+                }
                 /* Create all possible links for endpoint */
                 if (!(0, core_1.isStandardDatatype)(attributeDatatypeId)) {
                     links[`${label}.${attributeLabel}`] = {

package/lib/SwaggerGenerationServiceRunner.js

@@ -32,6 +32,16 @@ class SwaggerGenerationServiceRunner extends core_1.AppRunner {
             .option('contactURL', { describe: 'API contact URL.' })
             .option('licenseName', { describe: 'API license name.' })
             .option('licenseURL', { describe: 'API license URL.' })
+            .option('excludeClasses', {
+            describe: 'A list of class names to exclude from the output.',
+            type: 'string',
+            array: true,
+        })
+            .option('excludeProperties', {
+            describe: 'A list of property names to exclude from the output.',
+            type: 'string',
+            array: true,
+        })
             .option('silent', {
             describe: 'All logs are suppressed',
             default: false,

package/lib/config/SwaggerGenerationServiceConfiguration.d.ts

@@ -56,6 +56,14 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
      * API metadata: license URL
      */
     private _licenseURL;
+    /**
+     * An array of class names to be excluded from the generated output
+     */
+    private _excludeClasses;
+    /**
+     * An array of property names to be excluded from the generated output
+     */
+    private _excludeProperties;
     createFromCli(params: YargsParams): Promise<void>;
     get input(): string;
     get output(): string;
@@ -71,4 +79,6 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
     get contactEmail(): string | undefined;
     get licenseName(): string | undefined;
     get licenseURL(): string | undefined;
+    get excludeClasses(): string[];
+    get excludeProperties(): string[];
 }

package/lib/config/SwaggerGenerationServiceConfiguration.js

@@ -24,6 +24,8 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
         this._contactEmail = params.contactEmail;
         this._licenseName = params.licenseName;
         this._licenseURL = params.licenseURL;
+        this._excludeClasses = params.excludeClasses;
+        this._excludeProperties = params.excludeProperties;
     }
     get input() {
         if (!this._input) {
@@ -91,6 +93,12 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
     get licenseURL() {
         return this._licenseURL;
     }
+    get excludeClasses() {
+        return this._excludeClasses || [];
+    }
+    get excludeProperties() {
+        return this._excludeProperties || [];
+    }
 };
 SwaggerGenerationServiceConfiguration = __decorate([
     (0, inversify_1.injectable)()

package/lib/enums/Properties.d.ts

@@ -1 +1 @@
-export declare const mapProperties: (datatype: string, label: string, subclasses: string[], abstract: boolean) => object;
+export declare const mapProperties: (datatype: string, label: string, subclasses: string[], abstract: boolean, excludeClasses: string[]) => object | undefined;

package/lib/enums/Properties.js

@@ -32,37 +32,44 @@ const Properties = new Map([
     [core_1.ns.xsd('decimal').value, { '@value': { type: 'string', pattern: '(+|-)?([0-9]+(.[0-9]*)?|.[0-9]+)' }, '@type': { type: 'string', pattern: '^Decimal$' } }],
 ]);
 /* eslint-enable max-len*/
-const mapProperties = (datatype, label, subclasses, abstract) => {
+const mapProperties = (datatype, label, subclasses, abstract, excludeClasses) => {
     /* Primitive data type conversion from Linked Data to Swagger */
     if (Properties.has(datatype)) {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return Properties.get(datatype);
     }
-    /* Multiple subclasses requires a discriminator to link both the superclass and subclasses as schemas */
-    if (subclasses.length > 0) {
-        const mapping = {};
-        const oneOf = [];
-        /* Only allow super class if it is not abstract */
-        if (!abstract) {
-            mapping[label] = `#/components/schemas/${label}`;
-            oneOf.push({ $ref: `#/components/schemas/${label}` });
-        }
-        for (const subclass of subclasses) {
-            const ref = `#/components/schemas/${subclass}`;
-            oneOf.push({ $ref: ref });
-            mapping[subclass] = ref;
+    const oneOf = [];
+    // Add the superclass to the list if it's not abstract and not excluded
+    if (!abstract && !excludeClasses.includes(label)) {
+        oneOf.push({ $ref: `#/components/schemas/${label}` });
+    }
+    // Add all subclasses that are not excluded
+    for (const subclass of subclasses) {
+        if (!excludeClasses.includes(subclass)) {
+            oneOf.push({ $ref: `#/components/schemas/${subclass}` });
         }
-        return {
-            oneOf,
-            discriminator: {
-                propertyName: '@type',
-                mapping,
-            },
-        };
     }
-    /* Regular schemas without any subclassing */
+    // If no valid classes are left for this property, it should be omitted
+    if (oneOf.length === 0) {
+        return undefined;
+    }
+    // If only one class remains, we don't need a discriminator
+    if (oneOf.length === 1) {
+        return oneOf[0];
+    }
+    // If multiple classes remain, build the discriminator object
+    const mapping = {};
+    for (const item of oneOf) {
+        const refParts = item.$ref.split('/');
+        const className = refParts[refParts.length - 1];
+        mapping[className] = item.$ref;
+    }
     return {
-        $ref: `#/components/schemas/${label}`,
+        oneOf,
+        discriminator: {
+            propertyName: '@type',
+            mapping,
+        },
     };
 };
 exports.mapProperties = mapProperties;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oslo-flanders/swagger-generator",
-  "version": "1.0.4",
+  "version": "1.1.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",
@@ -36,20 +36,20 @@
     "url": "https://github.com/Informatievlaanderen/OSLO-UML-Transformer/issues"
   },
   "devDependencies": {
-    "@rdfjs/types": "^1.1.0",
+    "@rdfjs/types": "^2.0.0",
     "@types/streamify-array": "^1.0.0"
   },
   "dependencies": {
-    "@oslo-flanders/core": "^1.0.0",
+    "@oslo-flanders/core": "^1.1.0",
     "inversify": "^6.0.1",
-    "n3": "^1.16.2",
-    "rdf-data-factory": "^1.1.1",
-    "rdf-parse": "^2.3.2",
-    "rdf-serialize": "^2.2.2",
-    "reflect-metadata": "^0.1.13",
-    "streamify-array": "^1.0.1",
+    "n3": "^2.0.0",
+    "rdf-data-factory": "^2.0.0",
+    "rdf-parse": "^5.0.0",
+    "rdf-serialize": "^5.1.0",
+    "reflect-metadata": "^0.2.1",
+    "streamify-array": "^2.0.0",
     "streamify-string": "^1.0.1",
-    "yargs": "^17.6.0"
+    "yargs": "^18.0.0"
   },
   "gitHead": "beaa3821b72a7df104ff61af49fed6c1140fadd8"
 }