@oslo-flanders/swagger-generator 1.1.0 → 1.2.0

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.d.ts

@@ -10,6 +10,7 @@ export declare class SwaggerGenerationService implements IService {
     private getProbleemdetailsLink;
     private getContact;
     private getLicense;
+    private schemaExists;
     init(): Promise<void>;
     run(): Promise<void>;
     createSwagger(schemas: any, links: any): Object;

package/lib/SwaggerGenerationService.js

@@ -89,6 +89,15 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             url: this.configuration.licenseURL,
         };
     }
+    /* The schema already exists in the model. This would mean that there are identical labels, which isn't ideal
+    https://vlaamseoverheid.atlassian.net/browse/DATAST-2249?atlOrigin=eyJpIjoiMWYyZjVmOTFhMWExNDc4MmIwMGQxNjhkMjJmN2NhZGUiLCJwIjoiaiJ9
+    */
+    schemaExists(schema, label) {
+        if (schema[label]) {
+            this.logger.warn(`[SwaggerGenerationService]: Schema already exists for the label (${label}) and will be overwritten.`);
+        }
+        return !!schema[label];
+    }
     async init() {
         return this.store.addQuadsFromFile(this.configuration.input);
     }
@@ -152,6 +161,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}.`))
@@ -248,7 +261,7 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const schemas = {};
         /* Create schema for each enumeration */
-        for (const enumId of this.store.findSubjects(core_1.ns.oslo('assignedURI'), core_1.ns.skos('Concept'))) {
+        for (const enumId of this.store.getEnumerations()) {
             let label = (_a = (0, core_1.getApplicationProfileLabel)(enumId, this.store, this.configuration.language)) === null || _a === void 0 ? void 0 : _a.value;
             if (!label) {
                 this.logger.error(`Unknown enum label for ${enumId.value}`);
@@ -256,6 +269,7 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             }
             /* Class labels should be always pascal cased */
             label = (0, core_1.toPascalCase)(label);
+            this.schemaExists(schemas, label);
             schemas[label] = {
                 title: label,
                 type: 'object',
@@ -273,7 +287,9 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         for (const classId of [
             ...this.store.findSubjects(core_1.ns.rdf('type'), core_1.ns.owl('Class')),
             ...this.store.findSubjects(core_1.ns.rdf('type'), core_1.ns.rdfs('Datatype')),
-        ]) {
+        ]
+            // Extra filter to exclude all the enumerations since these are mentioned twice in the intermedairy format under enums and classes
+            .filter((val) => !(0, core_1.isEnumeration)(this.store, val))) {
             const assignedUri = this.store.getAssignedUri(classId);
             /* Primitive datatypes may not be generated */
             if (assignedUri && [...core_1.DataTypes.values()].includes(assignedUri.value))
@@ -294,6 +310,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 +331,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 +369,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;
@@ -395,6 +424,7 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                     },
                 };
             }
+            this.schemaExists(schemas, label);
             /* Create components for each schema */
             schemas[label] = {
                 title: label,
@@ -437,6 +467,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 +481,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 +497,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

@@ -30,39 +30,47 @@ const Properties = new Map([
     [core_1.ns.xsd('unsignedShort').value, { '@value': { type: 'number', format: 'int32', minimum: 0, maximum: 65535 }, '@type': { type: 'string', pattern: '^UnsignedShort$' } }],
     [core_1.ns.xsd('unsignedByte').value, { '@value': { type: 'number', format: 'int32', minimum: 0, maximum: 255 }, '@type': { type: 'string', pattern: '^UnsignedByte$' } }],
     [core_1.ns.xsd('decimal').value, { '@value': { type: 'string', pattern: '(+|-)?([0-9]+(.[0-9]*)?|.[0-9]+)' }, '@type': { type: 'string', pattern: '^Decimal$' } }],
+    [core_1.ns.xsd('language').value, { '@value': { type: 'string', pattern: '^[a-z]{2,3}(-[A-Z]{2})?' }, '@type': { type: 'string', pattern: '^Language$' } }],
 ]);
 /* 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/lib/types/Swagger.d.ts

@@ -91,3 +91,6 @@ export interface SwaggerLink {
     parameters: Record<string, string>;
     description: string;
 }
+export interface Schema {
+    [key: string]: any;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oslo-flanders/swagger-generator",
-  "version": "1.1.0",
+  "version": "1.2.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",
@@ -40,7 +40,7 @@
     "@types/streamify-array": "^1.0.0"
   },
   "dependencies": {
-    "@oslo-flanders/core": "^1.1.0",
+    "@oslo-flanders/core": "^1.2.0",
     "inversify": "^6.0.1",
     "n3": "^2.0.0",
     "rdf-data-factory": "^2.0.0",