Incorrect path generated

[FranDepascuali]

Describe the bug
When I generate the openapi spec, it doesn't resolve imports correctly
Check the schemas.

With this:

import SubscriptionTiers from '@kamara/backend/src/database/__tables__/public/SubscriptionTiers.js';
...
export type SubscriptionsApiSpec = Tspec.DefineApiSpec<{
  tags: ['Subscriptions'];
  paths: {
    '/subscriptions': {
      get: {
        summary: 'Get all subscription tiers';
        response: {
          200: SubscriptionTiers;
        };
        // handler: typeof SubscriptionsController.getAllSubscriptionTiers;
      };
    };
  };
}>;

Generated openapi

{
  "info": {
    "title": "Tspec API",
    "version": "0.0.1",
    "description": ""
  },
  "openapi": "3.0.3",
  "paths": {
    "/subscriptions": {
      "get": {
        "operationId": "SubscriptionsApiSpec_get_/subscriptions",
        "tags": [
          "Subscriptions"
        ],
        "summary": "Get all subscription tiers",
        "parameters": [],
        "responses": {}
      }
    }
  },
  "components": {
    "schemas": {
      "import__apps_backend_src_database___tables___public_SubscriptionTiers___assert___resolution-mode___import____.default": {
        "description": "Represents the table public.subscription_tiers",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/import__apps_backend_src_database___tables___public_SubscriptionTiers___assert___resolution-mode___import____.SubscriptionTiersId"
          },
          "subscription_type": {
            "type": "string"
          },
          "monthly_price": {
            "type": "string"
          },
          "repository_limit": {
            "type": "number"
          },
          "monthly_credits": {
            "type": "number"
          },
          "created_at": {
            "type": "string",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "required": [
          "created_at",
          "id",
          "monthly_credits",
          "monthly_price",
          "repository_limit",
          "subscription_type",
          "updated_at"
        ]
      },
      "import__apps_backend_src_database___tables___public_SubscriptionTiers___assert___resolution-mode___import____.SubscriptionTiersId": {
        "description": "Identifier type for public.subscription_tiers",
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "__brand": {
            "type": "string",
            "enum": [
              "SubscriptionTiersId"
            ]
          }
        },
        "required": [
          "__brand"
        ]
      }
    }
  }
}

[hyeonss0417]

Thank you for reporting this issue!

This is a known limitation of the underlying typescript-json-schema library. When types are imported from external modules (especially with path aliases like @kamara/backend/...), the library generates schema names based on the full import path, resulting in these long, complex names.

Two issues here:

1. Schema naming: The long import path is used as the schema name
2. Empty responses: The responses object is empty, suggesting the type reference isn't being resolved correctly

Workarounds:

1. Re-export the type locally: Instead of using the imported type directly, create a local type alias:

   import SubscriptionTiersOriginal from '@kamara/backend/src/database/__tables__/public/SubscriptionTiers.js';
   
   // Create a local type alias
   type SubscriptionTiers = SubscriptionTiersOriginal;
   
   export type SubscriptionsApiSpec = Tspec.DefineApiSpec<{
     // ...
     responses: {
       200: SubscriptionTiers;
     };
   }>;

2. Define the interface locally: If the type is simple, define it in the same file:

   interface SubscriptionTiers {
     id: number;
     subscription_type: string;
     // ... other properties
   }

3. Use @title JSDoc annotation: You can override the schema title:

   /** @title SubscriptionTiers */
   type SubscriptionTiers = SubscriptionTiersOriginal;

Root Cause:
The typescript-json-schema library uses the TypeScript compiler's internal symbol names for imported types, which include the full module path. This is particularly problematic with:

• Path aliases (@kamara/...)
• ESM imports with .js extensions
• Default exports

We're tracking this as a potential enhancement to add schema name normalization in a future release. In the meantime, the workarounds above should help.