@oslo-flanders/swagger-generator 1.4.0 → 2.0.0

package/README.md

@@ -37,6 +37,10 @@ The service is executed from the CLI and expects the following parameters:
 | `--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 |
+| `--disableLinks` | Disable the creation of links | No | `true` or `false` (default) |
+| `--expanded` | Disable the creation of links | No | `true` or `false` (default) |
+| `--excludeClassesExpanded` | Classes to exclude from expanding their properties in JSON-LD | No | Persoon Organisatie Test |
+| `--excludePropertiesExpanded` | Properties to exclude from expanding in JSON-LD | No | voornaam achternaam |
 | `--outputFormat` | Output format for the generated files. Can be specified multiple times to generate multiple formats at once. | No | `application/json` (default) or `application/yaml` |
 | `--silent` | Suppress log messages | No | `true` or `false` (default) |
 

package/lib/SwaggerGenerationService.d.ts

@@ -6,14 +6,14 @@ export declare class SwaggerGenerationService implements IService {
     readonly configuration: SwaggerGenerationServiceConfiguration;
     readonly store: QuadStore;
     constructor(logger: Logger, config: SwaggerGenerationServiceConfiguration, store: QuadStore);
-    private getProbleemdetailsContent;
-    private getProbleemdetailsLink;
+    private getProblemdetailsContent;
+    private getProblemdetailsLink;
     private getContact;
     private getLicense;
     private schemaExists;
     init(): Promise<void>;
     run(): Promise<void>;
-    createSwagger(schemas: any, links: any): Object;
+    createSwagger(schemas: any, links?: any): Object;
     createSchemas(): Object;
     createLinks(): Object;
     writeOutput(outputFormat: OutputFormat, obj: Object, outputPath: string): Promise<void>;

package/lib/SwaggerGenerationService.js

@@ -53,23 +53,23 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         this.configuration = config;
         this.store = store;
     }
-    getProbleemdetailsContent() {
+    getProblemdetailsContent() {
         return {
             [core_1.OutputFormat.JsonProblem]: {
                 schema: {
-                    $ref: '#/components/schemas/Probleemdetail',
+                    $ref: '#/components/schemas/Problemdetail',
                 },
             },
         };
     }
-    getProbleemdetailsLink(label) {
+    getProblemdetailsLink(label) {
         return {
-            'Probleemdetail.type': {
+            'Problemdetail.type': {
                 operationId: `${label}GET`,
                 parameters: {
                     type: `$response.body#/type`,
                 },
-                description: 'De waarde van het attribuut `type` kan gebruikt worden om het gerefereerde object van het type `ProblemDetails` op te halen.',
+                description: 'De waarde van het attribuut `type` kan gebruikt worden om het gerefereerde object van het type `Problemdetail` op te halen.',
             },
         };
     }
@@ -110,7 +110,9 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         var _a;
         /* Create schemas and links once, then write for each output format */
         const schemas = this.createSchemas();
-        const links = this.createLinks();
+        const links = this.configuration.disableLinks
+            ? {}
+            : this.createLinks();
         /* Create self-standing referenceable components */
         const components = {
             openapi: this.configuration.versionSwagger,
@@ -121,7 +123,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 license: this.getLicense(),
                 version: this.configuration.versionAPI,
             },
-            components: { schemas, links },
+            components: {
+                schemas,
+                ...(Object.keys(links).length > 0 ? { links } : {}),
+            },
         };
         /* Create Swagger endpoint paths as example */
         const swagger = this.createSwagger(schemas, links);
@@ -135,7 +140,7 @@ let SwaggerGenerationService = class SwaggerGenerationService {
             await this.writeOutput(format, swagger, `swagger/example${ext}`);
         }
     }
-    createSwagger(schemas, links) {
+    createSwagger(schemas, links = {}) {
         var _a, _b, _c;
         const swagger = {
             openapi: this.configuration.versionSwagger,
@@ -159,6 +164,9 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         for (const classId of this.store.findSubjects(core_1.ns.rdf('type'), core_1.ns.owl('Class'))) {
             if (hasRootClasses && !this.store.isRootClass(classId))
                 continue;
+            /* Abstract classes should never be materialized as endpoint */
+            if (this.store.isAbstractClass(classId))
+                continue;
             const filteredLinks = {};
             let label = (_a = (0, core_1.getApplicationProfileLabel)(classId, this.store, this.configuration.language)) === null || _a === void 0 ? void 0 : _a.value;
             const definition = (_b = (0, core_1.getApplicationProfileDefinition)(classId, this.store, this.configuration.language)) === null || _b === void 0 ? void 0 : _b.value;
@@ -205,53 +213,55 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                                     },
                                 },
                             },
-                            links: filteredLinks,
+                            ...(Object.keys(filteredLinks).length > 0
+                                ? { links: filteredLinks }
+                                : {}),
                         },
                         /* Error codes follow the RFC 7807 */
                         400: {
                             description: 'Invalid data supplied.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         401: {
                             description: 'Invalid authorization.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         403: {
                             description: 'Authentication failed.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         404: {
                             description: 'Resource not found.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         412: {
                             description: 'Pre-condition failed.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         500: {
                             description: 'Unexpected Server Error.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         502: {
                             description: 'Bad Gateway.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         503: {
                             description: 'Service unavailable.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                         504: {
                             description: 'Gateway Timeout.',
-                            content: this.getProbleemdetailsContent(),
-                            links: this.getProbleemdetailsLink(label),
+                            content: this.getProblemdetailsContent(),
+                            links: this.getProblemdetailsLink(label),
                         },
                     },
                 },
@@ -261,6 +271,32 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         swagger.components = {
             schemas: {},
         };
+        /* Add minimal ProblemDetail in case it is not present, but needed for example Swagger */
+        swagger.components.schemas['Problemdetail'] = {
+            title: 'Problemdetail',
+            type: 'object',
+            description: 'Meer gedetailleerde beschrijving van de fout in een HTTP response.',
+            properties: {
+                type: {
+                    type: 'string',
+                    format: 'uri',
+                },
+                title: {
+                    type: 'string',
+                },
+                status: {
+                    type: 'integer',
+                    format: 'int64',
+                },
+                detail: {
+                    type: 'string',
+                },
+                instance: {
+                    type: 'string',
+                    format: 'uri',
+                },
+            },
+        };
         for (const schemaLabel of Object.keys(schemas))
             swagger.components.schemas[schemaLabel] = schemas[schemaLabel];
         return swagger;
@@ -375,9 +411,17 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                     this.logger.error(`Unknown cardinality for attribute ${attributeId.value}`);
                     continue;
                 }
+                /* Expanded JSON-LD depends on configuration */
+                let expanded = this.configuration.expanded;
+                if (this.configuration.excludeClassesExpanded.includes(label)) {
+                    expanded = false;
+                }
+                if (this.configuration.excludePropertiesExpanded.includes(`${label}.${attributeLabel}`)) {
+                    expanded = false;
+                }
                 /* 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, this.configuration.excludeClasses);
+                const properties = (0, Properties_1.mapProperties)(attributeDatatypeId, attributeDatatypeLabel, subclasses, attributeDatatypeAbstract, this.configuration.excludeClasses, expanded);
                 // If mapProperties returns nothing, the property pointed to an excluded class (this.configuration.excludeClasses)
                 if (!properties) {
                     continue;
@@ -390,13 +434,22 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                 if (isPrimitive) {
                     /* Wrap primitive property in its own named schema to avoid naming collisions */
                     const schemaName = `${label}.${attributeLabel}`;
-                    schemas[schemaName] = {
-                        title: schemaName,
-                        type: 'object',
-                        description: description,
-                        properties: properties,
-                        required: requiredProperties,
-                    };
+                    if (expanded) {
+                        schemas[schemaName] = {
+                            title: schemaName,
+                            type: 'object',
+                            description: description,
+                            properties: properties,
+                            required: requiredProperties,
+                        };
+                    }
+                    else {
+                        schemas[schemaName] = {
+                            title: schemaName,
+                            description: description,
+                            ...properties,
+                        };
+                    }
                     item = { $ref: `#/components/schemas/${schemaName}` };
                 }
                 else {
@@ -530,7 +583,10 @@ let SwaggerGenerationService = class SwaggerGenerationService {
     async writeOutput(outputFormat, obj, outputPath) {
         const isYaml = outputFormat === core_1.OutputFormat.Yaml;
         const data = isYaml
-            ? yaml.dump(JSON.parse(JSON.stringify(obj)), { noRefs: true, lineWidth: -1 })
+            ? yaml.dump(JSON.parse(JSON.stringify(obj)), {
+                noRefs: true,
+                lineWidth: -1,
+            })
             : JSON.stringify(obj, null, 2);
         const filePath = path.join(this.configuration.output, outputPath);
         (0, core_1.ensureOutputDirectory)(path.dirname(filePath));

package/lib/SwaggerGenerationServiceRunner.js

@@ -41,6 +41,26 @@ class SwaggerGenerationServiceRunner extends core_1.AppRunner {
             describe: 'A list of property names to exclude from the output.',
             type: 'string',
             array: true,
+        })
+            .option('disableLinks', {
+            describe: 'Disable the creation of links.',
+            default: false,
+            boolean: true,
+        })
+            .option('expanded', {
+            describe: 'Use JSON-LD expanded format instead of default compact format.',
+            default: false,
+            boolean: true,
+        })
+            .option('excludeClassesExpanded', {
+            describe: 'A list of class names to exclude from expanding their properties with JSON-LD expansion.',
+            type: 'string',
+            array: true,
+        })
+            .option('excludePropertiesExpanded', {
+            describe: 'A list of property names to exclude from JSON-LD expansion.',
+            type: 'string',
+            array: true,
         })
             .option('silent', {
             describe: 'All logs are suppressed',

package/lib/config/SwaggerGenerationServiceConfiguration.d.ts

@@ -69,6 +69,22 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
      * Output formats
      */
     private _outputFormat;
+    /**
+     * Whether to disable the creation of links
+     */
+    private _disableLinks;
+    /**
+     * Whether to use expanded JSON-LD format or not
+     */
+    private _expanded;
+    /**
+     * An array of class names to be excluded from expansion
+     */
+    private _excludeClassesExpanded;
+    /**
+     * An array of property names to be excluded from expansion
+     */
+    private _excludePropertiesExpanded;
     createFromCli(params: YargsParams): Promise<void>;
     get input(): string;
     get output(): string;
@@ -87,4 +103,8 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
     get excludeClasses(): string[];
     get excludeProperties(): string[];
     get outputFormat(): OutputFormat[];
+    get disableLinks(): boolean;
+    get expanded(): boolean;
+    get excludeClassesExpanded(): string[];
+    get excludePropertiesExpanded(): string[];
 }

package/lib/config/SwaggerGenerationServiceConfiguration.js

@@ -28,6 +28,10 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
         this._excludeClasses = params.excludeClasses;
         this._excludeProperties = params.excludeProperties;
         this._outputFormat = params.outputFormat;
+        this._disableLinks = params.disableLinks;
+        this._expanded = params.expanded;
+        this._excludeClassesExpanded = params.excludeClassesExpanded;
+        this._excludePropertiesExpanded = (params.excludePropertiesExpanded);
     }
     get input() {
         if (!this._input) {
@@ -104,6 +108,18 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
     get outputFormat() {
         return this._outputFormat || [core_1.OutputFormat.Json];
     }
+    get disableLinks() {
+        return !!this._disableLinks;
+    }
+    get expanded() {
+        return !!this._expanded;
+    }
+    get excludeClassesExpanded() {
+        return this._excludeClassesExpanded || [];
+    }
+    get excludePropertiesExpanded() {
+        return this._excludePropertiesExpanded || [];
+    }
 };
 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, excludeClasses: string[]) => object | undefined;
+export declare const mapProperties: (datatype: string, label: string, subclasses: string[], abstract: boolean, excludeClasses: string[], expanded: boolean) => object | undefined;

package/lib/enums/Properties.js

@@ -4,7 +4,7 @@ exports.mapProperties = void 0;
 /* eslint-disable @typescript-eslint/no-loss-of-precision */
 const core_1 = require("@oslo-flanders/core");
 /* eslint-disable max-len */
-const Properties = new Map([
+const PropertiesExpanded = new Map([
     [core_1.ns.rdf('langString').value, { '@value': { type: 'string' }, '@language': { type: 'string', pattern: '^nl$' } }],
     [core_1.ns.rdfs('Literal').value, { '@value': { type: 'string' }, '@type': { type: 'string' } }],
     [core_1.ns.xsd('string').value, { '@value': { type: 'string' } }],
@@ -32,12 +32,49 @@ 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$' } }],
     [core_1.ns.xsd('language').value, { '@value': { type: 'string', pattern: '^[a-z]{2,3}(-[A-Z]{2})?' }, '@type': { type: 'string', pattern: '^Language$' } }],
 ]);
+/* JSON-LD context provides values for @type and @language for primitive datatypes */
+const PropertiesCompacted = new Map([
+    [core_1.ns.rdf('langString').value, { type: 'string' }],
+    [core_1.ns.rdfs('Literal').value, { type: 'string' }],
+    [core_1.ns.xsd('string').value, { type: 'string' }],
+    [core_1.ns.xsd('anyURI').value, { type: 'string', format: 'uri' }],
+    [core_1.ns.xsd('dateTime').value, { type: 'string', format: 'date-time' }],
+    [core_1.ns.xsd('date').value, { type: 'string', format: 'date' }],
+    [core_1.ns.xsd('boolean').value, { type: 'boolean' }],
+    [core_1.ns.xsd('integer').value, { type: 'number', format: 'int64' }],
+    [core_1.ns.xsd('long').value, { type: 'number', format: 'int64', minimum: -9223372036854776000, maximum: 9223372036854776000 }],
+    [core_1.ns.xsd('float').value, { type: 'number', format: 'float' }],
+    [core_1.ns.xsd('double').value, { type: 'number', format: 'double' }],
+    [core_1.ns.xsd('int').value, { type: 'number', format: 'int32', minimum: -2147483648, maximum: 2147483647 }],
+    [core_1.ns.xsd('short').value, { type: 'number', format: 'int32', minimum: -32768, maximum: 32767 }],
+    [core_1.ns.xsd('byte').value, { type: 'number', format: 'int32', minimum: -128, maximum: 127 }],
+    [core_1.ns.xsd('hexBinary').value, { type: 'string', format: 'binary' }],
+    [core_1.ns.xsd('base64Binary').value, { type: 'string', format: 'byte' }],
+    [core_1.ns.xsd('nonNegativeInteger').value, { type: 'number', format: 'int64' }],
+    [core_1.ns.xsd('nonPositiveInteger').value, { type: 'number', format: 'int64' }],
+    [core_1.ns.xsd('negativeInteger').value, { type: 'number', format: 'int64', maximum: 0 }],
+    [core_1.ns.xsd('positiveInteger').value, { type: 'number', format: 'int64', minimum: 1 }],
+    [core_1.ns.xsd('unsignedLong').value, { type: 'number', format: 'int64', minimum: 0, maximum: 18446744073709552000 }],
+    [core_1.ns.xsd('unsignedInt').value, { type: 'number', format: 'int32', minimum: 0, maximum: 4294967295 }],
+    [core_1.ns.xsd('unsignedShort').value, { type: 'number', format: 'int32', minimum: 0, maximum: 65535 }],
+    [core_1.ns.xsd('unsignedByte').value, { type: 'number', format: 'int32', minimum: 0, maximum: 255 }],
+    [core_1.ns.xsd('decimal').value, { type: 'string', pattern: '(+|-)?([0-9]+(.[0-9]*)?|.[0-9]+)' }],
+    [core_1.ns.xsd('language').value, { type: 'string', pattern: '^[a-z]{2,3}(-[A-Z]{2})?' }],
+]);
 /* eslint-enable max-len*/
-const mapProperties = (datatype, label, subclasses, abstract, excludeClasses) => {
+const mapProperties = (datatype, label, subclasses, abstract, excludeClasses, expanded) => {
     /* 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);
+    if (expanded) {
+        if (PropertiesExpanded.has(datatype)) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            return PropertiesExpanded.get(datatype);
+        }
+    }
+    else {
+        if (PropertiesCompacted.has(datatype)) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            return PropertiesCompacted.get(datatype);
+        }
     }
     const oneOf = [];
     // Add the superclass to the list if it's not abstract and not excluded

package/package.json

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