feat: partial support external refs in paths (#447)

Author: js2me

.changeset/silent-beds-greet.md

@@ -0,0 +1,5 @@
+---
+"swagger-typescript-api": minor
+---
+
+partial support external paths by ref (#447)

package.json

@@ -61,7 +61,8 @@
     "swagger-schema-official": "2.0.0-bab6bed",
     "swagger2openapi": "^7.0.8",
     "typescript": "~5.9.2",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.1",
+    "yummies": "5.7.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",

src/code-gen-process.ts

@@ -1,4 +1,4 @@
-import SwaggerParser, { type resolve } from "@apidevtools/swagger-parser";
+import type { resolve } from "@apidevtools/swagger-parser";
 import { consola } from "consola";
 import lodash from "lodash";
 import * as typescript from "typescript";
@@ -11,7 +11,6 @@ import { CodeGenConfig } from "./configuration.js";
 import { SchemaComponentsMap } from "./schema-components-map.js";
 import { SchemaParserFabric } from "./schema-parser/schema-parser-fabric.js";
 import { SchemaRoutes } from "./schema-routes/schema-routes.js";
-import { SchemaWalker } from "./schema-walker.js";
 import { SwaggerSchemaResolver } from "./swagger-schema-resolver.js";
 import { TemplatesWorker } from "./templates-worker.js";
 import { JavascriptTranslator } from "./translators/javascript.js";
@@ -45,24 +44,17 @@ export class CodeGenProcess {
   fileSystem: FileSystem;
   codeFormatter: CodeFormatter;
   templatesWorker: TemplatesWorker;
-  schemaWalker: SchemaWalker;
   javascriptTranslator: JavascriptTranslator;
-  swaggerParser: SwaggerParser;
   swaggerRefs: Awaited<ReturnType<typeof resolve>> | undefined | null;
 
   constructor(config: Partial<GenerateApiConfiguration["config"]>) {
     this.config = new CodeGenConfig(config);
-    this.swaggerParser = new SwaggerParser();
     this.fileSystem = new FileSystem();
     this.swaggerSchemaResolver = new SwaggerSchemaResolver(
       this.config,
       this.fileSystem,
     );
-    this.schemaWalker = new SchemaWalker(
-      this.config,
-      this.swaggerSchemaResolver,
-    );
-    this.schemaComponentsMap = new SchemaComponentsMap(this.config, this);
+    this.schemaComponentsMap = new SchemaComponentsMap(this.config);
     this.typeNameFormatter = new TypeNameFormatter(this.config);
     this.templatesWorker = new TemplatesWorker(
       this.config,
@@ -75,11 +67,9 @@ export class CodeGenProcess {
       this.templatesWorker,
       this.schemaComponentsMap,
       this.typeNameFormatter,
-      this.schemaWalker,
     );
     this.schemaRoutes = new SchemaRoutes(
       this.config,
-      this,
       this.schemaParserFabric,
       this.schemaComponentsMap,
       this.templatesWorker,
@@ -99,73 +89,35 @@ export class CodeGenProcess {
       templatesToRender: this.templatesWorker.getTemplates(this.config),
     });
 
-    const swagger = await this.swaggerSchemaResolver.create();
-
-    this.swaggerSchemaResolver.fixSwaggerSchema(swagger);
-
-    try {
-      this.swaggerRefs = await this.swaggerParser.resolve(
-        this.config.url || this.config.input || (this.config.spec as any),
-        {
-          continueOnError: true,
-          mutateInputSchema: true,
-          validate: {
-            schema: false,
-            spec: false,
-          },
-          resolve: {
-            external: true,
-            http: {
-              ...this.config.requestOptions,
-              headers: Object.assign(
-                {},
-                this.config.authorizationToken
-                  ? {
-                      Authorization: this.config.authorizationToken,
-                    }
-                  : {},
-                this.config.requestOptions?.headers ?? {},
-              ),
-            },
-          },
-        },
-      );
-      this.swaggerRefs.set("fixed-swagger-schema", swagger.usageSchema as any);
-      this.swaggerRefs.set(
-        "original-swagger-schema",
-        swagger.originalSchema as any,
-      );
-    } catch (e) {
-      consola.error(e);
-    }
+    const resolvedSwaggerSchema = await this.swaggerSchemaResolver.create();
 
     this.config.update({
-      swaggerSchema: swagger.usageSchema,
-      originalSchema: swagger.originalSchema,
+      resolvedSwaggerSchema: resolvedSwaggerSchema,
+      swaggerSchema: resolvedSwaggerSchema.usageSchema,
+      originalSchema: resolvedSwaggerSchema.originalSchema,
     });
 
-    this.schemaWalker.addSchema("$usage", swagger.usageSchema);
-    this.schemaWalker.addSchema("$original", swagger.originalSchema);
-
     consola.info("start generating your typescript api");
 
     this.config.update(
-      this.config.hooks.onInit(this.config, this) || this.config,
+      this.config.hooks.onInit?.(this.config, this) || this.config,
     );
 
     this.schemaComponentsMap.clear();
 
-    lodash.each(swagger.usageSchema.components, (component, componentName) =>
-      lodash.each(component, (rawTypeData, typeName) => {
-        this.schemaComponentsMap.createComponent(
-          this.schemaComponentsMap.createRef([
-            "components",
-            componentName,
-            typeName,
-          ]),
-          rawTypeData,
-        );
-      }),
+    lodash.each(
+      resolvedSwaggerSchema.usageSchema.components,
+      (component, componentName) =>
+        lodash.each(component, (rawTypeData, typeName) => {
+          this.schemaComponentsMap.createComponent(
+            this.schemaComponentsMap.createRef([
+              "components",
+              componentName,
+              typeName,
+            ]),
+            rawTypeData,
+          );
+        }),
     );
 
     // Set all discriminators at the top
@@ -190,13 +142,10 @@ export class CodeGenProcess {
       return parsed;
     });
 
-    this.schemaRoutes.attachSchema({
-      usageSchema: swagger.usageSchema,
-      parsedSchemas,
-    });
+    this.schemaRoutes.attachSchema(resolvedSwaggerSchema, parsedSchemas);
 
     const rawConfiguration = {
-      apiConfig: this.createApiConfig(swagger.usageSchema),
+      apiConfig: this.createApiConfig(resolvedSwaggerSchema.usageSchema),
       config: this.config,
       modelTypes: this.collectModelTypes(),
       hasSecurityRoutes: this.schemaRoutes.hasSecurityRoutes,
@@ -214,7 +163,7 @@ export class CodeGenProcess {
     };
 
     const configuration =
-      this.config.hooks.onPrepareConfig(rawConfiguration) || rawConfiguration;
+      this.config.hooks.onPrepareConfig?.(rawConfiguration) || rawConfiguration;
 
     if (this.fileSystem.pathIsExist(this.config.output)) {
       if (this.config.cleanOutput) {

src/configuration.ts

@@ -9,11 +9,11 @@ import type {
 } from "../types/index.js";
 import { ComponentTypeNameResolver } from "./component-type-name-resolver.js";
 import * as CONSTANTS from "./constants.js";
+import type { ResolvedSwaggerSchema } from "./resolved-swagger-schema.js";
 import type { MonoSchemaParser } from "./schema-parser/mono-schema-parser.js";
 import type { SchemaParser } from "./schema-parser/schema-parser.js";
 import type { Translator } from "./translators/translator.js";
 import { objectAssign } from "./util/object-assign.js";
-import SwaggerParser from "@apidevtools/swagger-parser";
 
 const TsKeyword = {
   Number: "number",
@@ -111,6 +111,7 @@ export class CodeGenConfig {
     ) => {},
     onFormatRouteName: (_routeInfo: unknown, _templateRouteName: unknown) => {},
   };
+  resolvedSwaggerSchema!: ResolvedSwaggerSchema;
   defaultResponseType;
   singleHttpClient = false;
   httpClientType = CONSTANTS.HTTP_CLIENT.FETCH;
@@ -440,7 +441,13 @@ export class CodeGenConfig {
     this.componentTypeNameResolver = new ComponentTypeNameResolver(this, []);
   }
 
-  update = (update: Partial<GenerateApiConfiguration["config"]>) => {
+  update = (
+    update: Partial<
+      GenerateApiConfiguration["config"] & {
+        resolvedSwaggerSchema: ResolvedSwaggerSchema;
+      }
+    >,
+  ) => {
     objectAssign(this, update);
     if (this.enumNamesAsValues) {
       this.extractEnums = true;

src/resolved-swagger-schema.ts

@@ -0,0 +1,105 @@
+import type { resolve } from "@apidevtools/swagger-parser";
+import consola from "consola";
+import type { OpenAPI } from "openapi-types";
+import type { AnyObject, Maybe, Primitive } from "yummies/utils/types";
+import type { CodeGenConfig } from "./configuration.js";
+
+export interface RefDetails {
+  ref: string;
+  isLocal: boolean;
+  externalUrlOrPath: Maybe<string>;
+  externalOpenapiFileName?: string;
+}
+
+export class ResolvedSwaggerSchema {
+  private parsedRefsCache = new Map<string, RefDetails>();
+
+  constructor(
+    private config: CodeGenConfig,
+    public usageSchema: OpenAPI.Document,
+    public originalSchema: OpenAPI.Document,
+    private resolvers: Awaited<ReturnType<typeof resolve>>[],
+  ) {
+    this.usageSchema = usageSchema;
+    this.originalSchema = originalSchema;
+  }
+
+  getRefDetails(ref: string): RefDetails {
+    if (!this.parsedRefsCache.has(ref)) {
+      const isLocal = ref.startsWith("#");
+
+      if (isLocal) {
+        this.parsedRefsCache.set(ref, {
+          ref,
+          isLocal,
+          externalUrlOrPath: null,
+        });
+      } else {
+        const externalUrlOrPath = ref.split("#")[0]!
+        let externalOpenapiFileName = (externalUrlOrPath.split('/').at(-1) || '')
+
+        if (externalOpenapiFileName.endsWith('.json') || externalOpenapiFileName.endsWith('.yaml')) {
+          externalOpenapiFileName = externalOpenapiFileName.slice(0, -5);
+        } else if (externalOpenapiFileName.endsWith('.yml')) {
+          externalOpenapiFileName = externalOpenapiFileName.slice(0, -4);
+        }
+
+
+        this.parsedRefsCache.set(ref, {
+          ref,
+          isLocal,
+          externalUrlOrPath,
+          externalOpenapiFileName,
+        }); 
+      }
+    }
+
+    return this.parsedRefsCache.get(ref)!;
+  }
+
+  isLocalRef(ref: string): boolean {
+    return this.getRefDetails(ref).isLocal;
+  }
+
+  getRef(ref: Maybe<string>): Maybe<AnyObject | Primitive> {
+    if (!ref) {
+      return null;
+    }
+
+    const resolvedByOrigRef = this.tryToResolveRef(ref);
+
+    if (resolvedByOrigRef) {
+      return resolvedByOrigRef;
+    }
+
+    // const ref.match(/\#[a-z]/)
+    if (/#[a-z]/.test(ref)) {
+      const fixedRef = ref.replace(/#[a-z]/, (match) => {
+        const [hashtag, char] = match.split("");
+        return `${hashtag}/${char}`;
+      });
+
+      return this.tryToResolveRef(fixedRef);
+    }
+
+    // this.tryToResolveRef(`@usage${ref}`) ??
+    // this.tryToResolveRef(`@original${ref}`)
+  }
+
+  private tryToResolveRef(ref: Maybe<string>) {
+    if (!this.resolvers || !ref) {
+      return null;
+    }
+
+    for (const resolver of this.resolvers) {
+      try {
+        const resolvedAsIs = resolver.get(ref);
+        return resolvedAsIs;
+      } catch (e) {
+        consola.debug(e);
+      }
+    }
+
+    return null;
+  }
+}