@ebarahona/loopback-openapi-v3 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed Barahona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @ebarahona/loopback-openapi-v3
+
+OpenAPI version compatibility enhancer for LoopBack 4. Supports emitting OpenAPI Specification (OAS) 3.0.x, 3.1.x, and 3.2.x specs from LoopBack-generated OpenAPI output, with nullable conversion and lossy downgrade diagnostics.
+
+LoopBack 4 generates OpenAPI 3.0 specs by default. This component transforms the output to OpenAPI 3.1 or 3.2, enabling JSON Schema compatibility (3.1) and SSE streaming support (3.2). It also handles downgrading from higher versions to lower ones for backward compatibility.
+
+## Install
+
+```bash
+npm install @ebarahona/loopback-openapi-v3
+```
+
+## Usage
+
+```typescript
+import {OpenApiVersionComponent, OpenApiVersionBindings} from '@ebarahona/loopback-openapi-v3';
+
+const app = new RestApplication();
+app.component(OpenApiVersionComponent);
+app.bind(OpenApiVersionBindings.CONFIG).to({version: '3.1.0'});
+```
+
+The spec served at `/openapi.json` will output `"openapi": "3.1.0"`.
+
+## Configuration
+
+```typescript
+app.bind(OpenApiVersionBindings.CONFIG).to({
+  // Target version: '3.0.0' (default, no-op), '3.1.0', or '3.2.0'
+  version: '3.1.0',
+
+  // Transform nullable fields from 3.0 format to 3.1+ format
+  // { type: 'string', nullable: true } -> { type: ['string', 'null'] }
+  // Defaults to true for 3.1+
+  transformNullable: true,
+});
+```
+
+## Supported Versions
+
+| Version | Status | Spec |
+|---|---|---|
+| 3.0.0 | Default (no-op) | [spec.openapis.org/oas/v3.0.3](https://spec.openapis.org/oas/v3.0.3.html) |
+| 3.1.0 | Supported | [spec.openapis.org/oas/v3.1.0](https://spec.openapis.org/oas/v3.1.0.html) |
+| 3.2.0 | Supported | [spec.openapis.org/oas/v3.2.0](https://spec.openapis.org/oas/v3.2.0.html) |
+
+## How It Works
+
+The component registers an OAS Enhancer that runs once at boot after LoopBack assembles the spec. The original spec is deep-cloned to prevent mutation. The transformed spec is cached by LoopBack and served on subsequent requests without re-processing.
+
+### Upgrades (3.0 -> 3.1/3.2)
+
+- `nullable: true` transformed to type arrays (`{ type: ['string', 'null'] }`)
+- Handles nullable with `oneOf`, `anyOf`, `allOf`, and no type
+
+### Downgrades (3.2 -> 3.0/3.1)
+
+Downgrades are lossy. Features that have no equivalent in lower versions are stripped with diagnostic warnings.
+
+**3.1 features stripped when targeting 3.0:**
+
+| Feature | Field |
+|---|---|
+| JSON Schema dialect | `jsonSchemaDialect` |
+| Webhooks | `webhooks` |
+| Reusable path items | `components.pathItems` |
+| SPDX license identifier | `info.license.identifier` |
+| Type arrays | `type: ['string', 'null']` reverted to `nullable: true` |
+
+**3.2 features stripped when targeting 3.0 or 3.1:**
+
+| Feature | Field |
+|---|---|
+| Document identity | `$self` |
+| Server name | `servers[].name` |
+| QUERY HTTP method | `paths.*. query` |
+| Additional HTTP methods | `paths.*.additionalOperations` |
+| Tag nesting | `tags[].summary`, `.parent`, `.kind` |
+| Querystring parameter | `parameters[].in: 'querystring'` converted to `'query'` |
+| OAuth2 device flow | `securitySchemes.*.flows.device` |
+| SSE streaming schema | `content.*.itemSchema` |
+| SSE streaming encoding | `content.*.itemEncoding`, `.prefixEncoding` |
+| Example formats | `examples.*.dataValue`, `.serializedValue` |
+| Reusable media types | `components.mediaTypes` |
+| XML text nodes | `xml.text` |
+
+### Diagnostics
+
+The transformer emits warnings for every stripped feature:
+
+```typescript
+import {transformOpenApiSpec} from '@ebarahona/loopback-openapi-v3';
+
+const {spec, warnings} = transformOpenApiSpec(inputSpec, {version: '3.0.0'});
+for (const w of warnings) {
+  console.log(`[${w.field}] ${w.message}`);
+}
+// [webhooks] Removed webhooks because target version is 3.0.x (webhooks require 3.1+)
+// [$self] Removed $self because target version is 3.0.x
+```
+
+### Pure Function API
+
+The transformer is available as a standalone pure function for use outside LoopBack:
+
+```typescript
+import {transformOpenApiSpec, parseVersion} from '@ebarahona/loopback-openapi-v3';
+
+const {spec, warnings} = transformOpenApiSpec(inputSpec, {version: '3.1.0'});
+```
+
+## Requirements
+
+- Node.js >= 18 (for `structuredClone`)
+- LoopBack 4 (`@loopback/core` >= 7.0.0)
+- `@loopback/openapi-v3` >= 11.0.0
+- `@loopback/rest` >= 15.0.0
+
+## Spec References
+
+- [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3.html)
+- [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0.html)
+- [OpenAPI 3.2.0](https://spec.openapis.org/oas/v3.2.0.html)
+- [OpenAPI Specification Repository](https://github.com/OAI/OpenAPI-Specification)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { OpenApiVersionComponent } from './openapi-version.component';
+export { OpenApiVersionEnhancer } from './openapi-version.enhancer';
+export { OpenApiVersionBindings } from './keys';
+export { OpenApiVersion, OpenApiVersionConfig } from './types';
+export { transformOpenApiSpec, parseVersion, TransformResult, TransformWarning, } from './transform';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVersion = exports.transformOpenApiSpec = exports.OpenApiVersionBindings = exports.OpenApiVersionEnhancer = exports.OpenApiVersionComponent = void 0;
+var openapi_version_component_1 = require("./openapi-version.component");
+Object.defineProperty(exports, "OpenApiVersionComponent", { enumerable: true, get: function () { return openapi_version_component_1.OpenApiVersionComponent; } });
+var openapi_version_enhancer_1 = require("./openapi-version.enhancer");
+Object.defineProperty(exports, "OpenApiVersionEnhancer", { enumerable: true, get: function () { return openapi_version_enhancer_1.OpenApiVersionEnhancer; } });
+var keys_1 = require("./keys");
+Object.defineProperty(exports, "OpenApiVersionBindings", { enumerable: true, get: function () { return keys_1.OpenApiVersionBindings; } });
+var transform_1 = require("./transform");
+Object.defineProperty(exports, "transformOpenApiSpec", { enumerable: true, get: function () { return transform_1.transformOpenApiSpec; } });
+Object.defineProperty(exports, "parseVersion", { enumerable: true, get: function () { return transform_1.parseVersion; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yEAAoE;AAA5D,oIAAA,uBAAuB,OAAA;AAC/B,uEAAkE;AAA1D,kIAAA,sBAAsB,OAAA;AAC9B,+BAA8C;AAAtC,8GAAA,sBAAsB,OAAA;AAE9B,yCAKqB;AAJnB,iHAAA,oBAAoB,OAAA;AACpB,yGAAA,YAAY,OAAA"}

package/dist/keys.d.ts

@@ -0,0 +1,6 @@
+import { BindingKey } from '@loopback/core';
+import { OpenApiVersionConfig } from './types';
+export declare namespace OpenApiVersionBindings {
+    const CONFIG: BindingKey<OpenApiVersionConfig>;
+    const COMPONENT = "openapi-version.component";
+}

package/dist/keys.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiVersionBindings = void 0;
+const core_1 = require("@loopback/core");
+var OpenApiVersionBindings;
+(function (OpenApiVersionBindings) {
+    OpenApiVersionBindings.CONFIG = core_1.BindingKey.create('openapi-version.config');
+    OpenApiVersionBindings.COMPONENT = 'openapi-version.component';
+})(OpenApiVersionBindings || (exports.OpenApiVersionBindings = OpenApiVersionBindings = {}));
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";;;AAAA,yCAA0C;AAG1C,IAAiB,sBAAsB,CAKtC;AALD,WAAiB,sBAAsB;IACxB,6BAAM,GAAG,iBAAU,CAAC,MAAM,CACrC,wBAAwB,CACzB,CAAC;IACW,gCAAS,GAAG,2BAA2B,CAAC;AACvD,CAAC,EALgB,sBAAsB,sCAAtB,sBAAsB,QAKtC"}

package/dist/openapi-version.component.d.ts

@@ -0,0 +1,4 @@
+import { Binding, Component } from '@loopback/core';
+export declare class OpenApiVersionComponent implements Component {
+    bindings: Binding[];
+}

package/dist/openapi-version.component.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiVersionComponent = void 0;
+const core_1 = require("@loopback/core");
+const openapi_v3_1 = require("@loopback/openapi-v3");
+const keys_1 = require("./keys");
+const openapi_version_enhancer_1 = require("./openapi-version.enhancer");
+const types_1 = require("./types");
+class OpenApiVersionComponent {
+    constructor() {
+        this.bindings = [
+            core_1.Binding.bind(keys_1.OpenApiVersionBindings.CONFIG).to(types_1.DEFAULT_CONFIG),
+            (0, core_1.createBindingFromClass)(openapi_version_enhancer_1.OpenApiVersionEnhancer).apply(openapi_v3_1.asSpecEnhancer),
+        ];
+    }
+}
+exports.OpenApiVersionComponent = OpenApiVersionComponent;
+//# sourceMappingURL=openapi-version.component.js.map

package/dist/openapi-version.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-version.component.js","sourceRoot":"","sources":["../src/openapi-version.component.ts"],"names":[],"mappings":";;;AAAA,yCAIwB;AACxB,qDAAoD;AACpD,iCAA8C;AAC9C,yEAAkE;AAClE,mCAAuC;AAavC,MAAa,uBAAuB;IAApC;QACE,aAAQ,GAAc;YACpB,cAAO,CAAC,IAAI,CAAC,6BAAsB,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,sBAAc,CAAC;YAC9D,IAAA,6BAAsB,EAAC,iDAAsB,CAAC,CAAC,KAAK,CAAC,2BAAc,CAAC;SACrE,CAAC;IACJ,CAAC;CAAA;AALD,0DAKC"}

package/dist/openapi-version.enhancer.d.ts

@@ -0,0 +1,8 @@
+import { OASEnhancer, OpenApiSpec } from '@loopback/openapi-v3';
+import { OpenApiVersionConfig } from './types';
+export declare class OpenApiVersionEnhancer implements OASEnhancer {
+    private options;
+    name: string;
+    constructor(options?: OpenApiVersionConfig);
+    modifySpec(spec: OpenApiSpec): OpenApiSpec;
+}

package/dist/openapi-version.enhancer.js

@@ -0,0 +1,46 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiVersionEnhancer = void 0;
+const core_1 = require("@loopback/core");
+const debug_1 = require("debug");
+const keys_1 = require("./keys");
+const transform_1 = require("./transform");
+const types_1 = require("./types");
+const debug = (0, debug_1.default)('loopback:openapi-version');
+let OpenApiVersionEnhancer = class OpenApiVersionEnhancer {
+    constructor(options = types_1.DEFAULT_CONFIG) {
+        this.options = options;
+        this.name = 'openapi-version';
+    }
+    modifySpec(spec) {
+        const opts = { ...types_1.DEFAULT_CONFIG, ...this.options };
+        debug('configured target OpenAPI version: %s (transformNullable=%s)', opts.version, opts.transformNullable !== false);
+        const result = (0, transform_1.transformOpenApiSpec)(spec, opts);
+        if (result.warnings.length > 0) {
+            debug('emitted %d OpenAPI compatibility warnings', result.warnings.length);
+            for (const w of result.warnings) {
+                debug('warning [%s]: %s', w.field, w.message);
+            }
+        }
+        return result.spec;
+    }
+};
+exports.OpenApiVersionEnhancer = OpenApiVersionEnhancer;
+exports.OpenApiVersionEnhancer = OpenApiVersionEnhancer = __decorate([
+    (0, core_1.injectable)(),
+    __param(0, (0, core_1.config)({ fromBinding: keys_1.OpenApiVersionBindings.CONFIG, optional: true })),
+    __metadata("design:paramtypes", [Object])
+], OpenApiVersionEnhancer);
+//# sourceMappingURL=openapi-version.enhancer.js.map

package/dist/openapi-version.enhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-version.enhancer.js","sourceRoot":"","sources":["../src/openapi-version.enhancer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,yCAAkD;AAKlD,iCAAiC;AACjC,iCAA8C;AAC9C,2CAAiD;AACjD,mCAA6D;AAE7D,MAAM,KAAK,GAAG,IAAA,eAAY,EAAC,0BAA0B,CAAC,CAAC;AAqBhD,IAAM,sBAAsB,GAA5B,MAAM,sBAAsB;IAGjC,YAEE,UAAwC,sBAAc;QAA9C,YAAO,GAAP,OAAO,CAAuC;QAJxD,SAAI,GAAG,iBAAiB,CAAC;IAKtB,CAAC;IAEJ,UAAU,CAAC,IAAiB;QAC1B,MAAM,IAAI,GAAG,EAAC,GAAG,sBAAc,EAAE,GAAG,IAAI,CAAC,OAAO,EAAC,CAAC;QAClD,KAAK,CACH,8DAA8D,EAC9D,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,iBAAiB,KAAK,KAAK,CACjC,CAAC;QACF,MAAM,MAAM,GAAG,IAAA,gCAAoB,EACjC,IAA+B,EAC/B,IAAI,CACL,CAAC;QAEF,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;YAC9B,KAAK,CAAC,2CAA2C,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC3E,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE;gBAC/B,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;aAC/C;SACF;QAED,OAAO,MAAM,CAAC,IAAmB,CAAC;IACpC,CAAC;CACF,CAAA;AA7BY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,iBAAU,GAAE;IAKR,WAAA,IAAA,aAAM,EAAC,EAAC,WAAW,EAAE,6BAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAC,CAAC,CAAA;;GAJ5D,sBAAsB,CA6BlC"}

package/dist/transform.d.ts

@@ -0,0 +1,19 @@
+import { OpenApiVersionConfig } from './types';
+interface Obj {
+    [key: string]: unknown;
+}
+export interface TransformWarning {
+    field: string;
+    message: string;
+}
+export interface TransformResult {
+    spec: Obj;
+    warnings: TransformWarning[];
+}
+export declare function parseVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export declare function transformOpenApiSpec(spec: Obj, config?: OpenApiVersionConfig): TransformResult;
+export {};