@oslo-flanders/swagger-generator 1.5.0 → 3.0.0

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: | |
@@ -37,8 +38,11 @@ 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 |
-| `--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` |
 | `--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) |
 
 ## Usage

package/lib/SwaggerGenerationService.d.ts

@@ -6,8 +6,8 @@ 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;

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.',
             },
         };
     }
@@ -130,14 +130,18 @@ let SwaggerGenerationService = class SwaggerGenerationService {
         };
         /* 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, swagger, `swagger/example${languageSuffix}${ext}`);
         }
     }
     createSwagger(schemas, links = {}) {
@@ -164,6 +168,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;
@@ -217,48 +224,48 @@ let SwaggerGenerationService = class SwaggerGenerationService {
                         /* 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),
                         },
                     },
                 },
@@ -268,6 +275,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;
@@ -382,9 +415,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;
@@ -397,13 +438,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 {
@@ -537,7 +587,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

@@ -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',
@@ -46,6 +50,21 @@ class SwaggerGenerationServiceRunner extends core_1.AppRunner {
             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',
@@ -66,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
      */
@@ -73,10 +78,23 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
      * 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;
     get language(): string;
+    get primaryLanguage(): string;
     get versionSwagger(): string;
     get versionAPI(): string;
     get title(): string;
@@ -92,4 +110,7 @@ export declare class SwaggerGenerationServiceConfiguration implements IConfigura
     get excludeProperties(): string[];
     get outputFormat(): OutputFormat[];
     get disableLinks(): boolean;
+    get expanded(): boolean;
+    get excludeClassesExpanded(): string[];
+    get excludePropertiesExpanded(): 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;
@@ -29,6 +30,9 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
         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) {
@@ -48,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.`);
@@ -108,6 +116,15 @@ let SwaggerGenerationServiceConfiguration = class SwaggerGenerationServiceConfig
     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.5.0",
+  "version": "3.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",