@skmtc/core 0.0.796 → 0.0.797

package/script/run/toV3JsonDocument.d.ts

@@ -1,7 +1,97 @@
 import "../_dnt.polyfills.js";
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+/**
+ * Union type representing any supported OpenAPI document version.
+ *
+ * SKMTC supports processing OpenAPI/Swagger documents from version 2.0 through 3.1,
+ * automatically converting them to OpenAPI 3.0 format for internal processing.
+ */
 type AnyOasDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3_1.Document;
+/**
+ * Parses a string into an OpenAPI document object.
+ *
+ * Automatically detects whether the input string is JSON or YAML format based on
+ * the content, then parses it into an OpenAPI document object. Supports all
+ * OpenAPI versions (2.0, 3.0.x, 3.1.x).
+ *
+ * @param schema - The OpenAPI document as a JSON or YAML string
+ * @returns Parsed OpenAPI document object
+ *
+ * @example Parsing JSON OpenAPI document
+ * ```typescript
+ * const jsonSchema = `{
+ *   "openapi": "3.0.0",
+ *   "info": { "title": "My API", "version": "1.0.0" },
+ *   "paths": {}
+ * }`;
+ * const document = stringToSchema(jsonSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @example Parsing YAML OpenAPI document
+ * ```typescript
+ * const yamlSchema = `
+ * openapi: 3.0.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ * const document = stringToSchema(yamlSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @throws {SyntaxError} If the JSON is malformed
+ * @throws {Error} If the YAML is malformed
+ */
 export declare const stringToSchema: (schema: string) => AnyOasDocument;
+/**
+ * Converts any OpenAPI document version to OpenAPI 3.0 format.
+ *
+ * SKMTC processes all documents using OpenAPI 3.0 as the internal format.
+ * This function handles version detection and conversion from:
+ * - OpenAPI 3.0.x (returned as-is)
+ * - OpenAPI 3.1.x (downgraded to 3.0 with allOf transformations)
+ * - Swagger 2.0 (upgraded to OpenAPI 3.0)
+ *
+ * @param schema - The OpenAPI document to convert
+ * @returns Promise resolving to an OpenAPI 3.0 document
+ *
+ * @example Converting OpenAPI 3.1 to 3.0
+ * ```typescript
+ * const openapi31Doc = {
+ *   openapi: "3.1.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi31Doc);
+ * console.log(v3Doc.openapi); // "3.0.3" (converted)
+ * ```
+ *
+ * @example Converting Swagger 2.0 to OpenAPI 3.0
+ * ```typescript
+ * const swagger2Doc = {
+ *   swagger: "2.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(swagger2Doc);
+ * console.log(v3Doc.openapi); // "3.0.0" (converted)
+ * ```
+ *
+ * @example OpenAPI 3.0 passthrough
+ * ```typescript
+ * const openapi30Doc = {
+ *   openapi: "3.0.2",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi30Doc);
+ * console.log(v3Doc === openapi30Doc); // true (same object)
+ * ```
+ *
+ * @throws {Error} If the document version is not recognized or supported
+ */
 export declare const toV3Document: (schema: AnyOasDocument) => Promise<OpenAPIV3.Document>;
 export {};
 //# sourceMappingURL=toV3JsonDocument.d.ts.map

package/script/run/toV3JsonDocument.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUtE,KAAK,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAEpF,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,cAM/C,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,QAAQ,cAAc,KAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CA0BrF,CAAA"}
+{"version":3,"file":"toV3JsonDocument.d.ts","sourceRoot":"","sources":["../../src/run/toV3JsonDocument.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUtE;;;;;GAKG;AACH,KAAK,cAAc,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,cAM/C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,YAAY,GAAU,QAAQ,cAAc,KAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CA0BrF,CAAA"}

package/script/run/toV3JsonDocument.js

@@ -9,6 +9,43 @@ const parse_js_1 = require("../deps/jsr.io/@std/yaml/1.0.9/parse.js");
 const openapi_down_convert_1 = require("@apiture/openapi-down-convert");
 const ts_pattern_1 = require("ts-pattern");
 const swagger2openapi_1 = __importDefault(require("swagger2openapi"));
+/**
+ * Parses a string into an OpenAPI document object.
+ *
+ * Automatically detects whether the input string is JSON or YAML format based on
+ * the content, then parses it into an OpenAPI document object. Supports all
+ * OpenAPI versions (2.0, 3.0.x, 3.1.x).
+ *
+ * @param schema - The OpenAPI document as a JSON or YAML string
+ * @returns Parsed OpenAPI document object
+ *
+ * @example Parsing JSON OpenAPI document
+ * ```typescript
+ * const jsonSchema = `{
+ *   "openapi": "3.0.0",
+ *   "info": { "title": "My API", "version": "1.0.0" },
+ *   "paths": {}
+ * }`;
+ * const document = stringToSchema(jsonSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @example Parsing YAML OpenAPI document
+ * ```typescript
+ * const yamlSchema = `
+ * openapi: 3.0.0
+ * info:
+ *   title: My API
+ *   version: 1.0.0
+ * paths: {}
+ * `;
+ * const document = stringToSchema(yamlSchema);
+ * console.log(document.info.title); // "My API"
+ * ```
+ *
+ * @throws {SyntaxError} If the JSON is malformed
+ * @throws {Error} If the YAML is malformed
+ */
 const stringToSchema = (schema) => {
     if (schema.trimStart().startsWith('{')) {
         return JSON.parse(schema);
@@ -18,6 +55,53 @@ const stringToSchema = (schema) => {
     }
 };
 exports.stringToSchema = stringToSchema;
+/**
+ * Converts any OpenAPI document version to OpenAPI 3.0 format.
+ *
+ * SKMTC processes all documents using OpenAPI 3.0 as the internal format.
+ * This function handles version detection and conversion from:
+ * - OpenAPI 3.0.x (returned as-is)
+ * - OpenAPI 3.1.x (downgraded to 3.0 with allOf transformations)
+ * - Swagger 2.0 (upgraded to OpenAPI 3.0)
+ *
+ * @param schema - The OpenAPI document to convert
+ * @returns Promise resolving to an OpenAPI 3.0 document
+ *
+ * @example Converting OpenAPI 3.1 to 3.0
+ * ```typescript
+ * const openapi31Doc = {
+ *   openapi: "3.1.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi31Doc);
+ * console.log(v3Doc.openapi); // "3.0.3" (converted)
+ * ```
+ *
+ * @example Converting Swagger 2.0 to OpenAPI 3.0
+ * ```typescript
+ * const swagger2Doc = {
+ *   swagger: "2.0",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(swagger2Doc);
+ * console.log(v3Doc.openapi); // "3.0.0" (converted)
+ * ```
+ *
+ * @example OpenAPI 3.0 passthrough
+ * ```typescript
+ * const openapi30Doc = {
+ *   openapi: "3.0.2",
+ *   info: { title: "My API", version: "1.0.0" },
+ *   paths: {}
+ * };
+ * const v3Doc = await toV3Document(openapi30Doc);
+ * console.log(v3Doc === openapi30Doc); // true (same object)
+ * ```
+ *
+ * @throws {Error} If the document version is not recognized or supported
+ */
 const toV3Document = async (schema) => {
     return await (0, ts_pattern_1.match)(schema)
         .with({ openapi: ts_pattern_1.P.string.startsWith('3.0') }, doc => doc)