swaggie 1.6.0 → 1.7.0-beta.1

package/README.md

@@ -10,152 +10,115 @@
 ![npm downloads](https://img.shields.io/npm/dw/swaggie.svg)
 ![npm install size](https://packagephobia.now.sh/badge?p=swaggie)
 
-Generate Typescript code from an OpenAPI 3.0 document, so that accessing REST API resources from the client code is less error-prone, static-typed and just easier to use long-term.
+Swaggie generates TypeScript client code from an OpenAPI 3 specification. Instead of writing API-fetching code by hand, you point Swaggie at your API spec and it outputs a fully typed, ready-to-use client — helping you catch errors at compile time rather than at runtime.
 
-You can take a look at the [Examples section](#example) down below.
+See the [Example section](#example) for a quick demo.
 
-Project is based and inspired by [OpenApi Client](https://github.com/mikestead/openapi-client).
+> Inspired by [OpenApi Client](https://github.com/mikestead/openapi-client).
 
-### Features
+---
 
-- Generate TypeScript code from OpenAPI 3.0 spec
-- Supports `fetch`, `axios`, `xior`, `SWR + axios`, `Angular 1`, `Angular 2+` templates. It's flexible.
-- Possible to create your own template that works with your existing codebase
-- It's a dev tool that generates code, so it's not a runtime dependency
-- Support for `allOf`, `oneOf`, `anyOf` and `$ref` in schemas
-- Support for different types of enums
-- Support for different content types
-- JSDoc comments for generated code
-- Small library size and very small and tree-shakable output that is all placed in one file
-- OpenAPI 3.1 is partially supported (mostly enums, more to come)
+## Features
 
-## Install
+- Generates TypeScript code from OpenAPI 3.0, 3.1, and 3.2 specs
+- Supports multiple HTTP client libraries out of the box: `fetch`, `axios`, `xior`, `SWR + axios`, `Angular 1`, `Angular 2+`, and `TanStack Query`
+- Custom templates — bring your own to fit your existing codebase
+- Supports `allOf`, `oneOf`, `anyOf`, `$ref`, nullable types, and various enum definitions
+- Handles multiple content types: JSON, plain text, multipart/form-data, URL-encoded, and binary
+- JSDoc comments on all generated functions
+- Generates a single, small, tree-shakable output file
+- Dev-only dependency — zero runtime overhead
 
-In your project
+---
 
-    npm install swaggie --save-dev
+## Installation
 
-Or globally to run CLI from anywhere
+Install as a dev dependency in your project:
 
-    npm install swaggie -g
-
-## OpenAPI versions
-
-Swaggie from version 1.0 supports OpenAPI 3.0 (and some features of 3.1). Swagger or OpenAPI 2.0 documents are not supported anymore, but you have few options how to deal with it:
-
-- **(preferred)** From your backend server generate OpenAPI 3.0 spec instead of version 2 (samples are updated to use OpenAPI 3.0)
-- Convert your OpenAPI 2.0 spec to 3.0 using [swagger2openapi](https://www.npmjs.com/package/swagger2openapi) tool (or something similar)
-- If you can't do that for any reason, you can stick to `Swaggie v0.x`. But upgrade is suggested
-
-Please note that OpenAPI 3.0 is a major spec upgrade and it's possible that there will be some breaking changes in the generated code.
-I have tried my best to minimize the impact, but it was not possible to avoid it completely.
-
-More info about breaking changes can be found in the [Releases](https://github.com/yhnavein/swaggie/releases).
-
-### CLI
-
-```
-Usage: swaggie [options]
-
-Options:
-
-  -V, --version             output the version number
-  -c, --config <path>       The path to the configuration JSON file. You can do all the set up there instead of parameters in the CLI
-  -s, --src <url|path>      The url or path to the Open API spec file
-  -o, --out <filePath>      The path to the file where the API would be generated. Use stdout if left empty
-  -b, --baseUrl <string>    Base URL that will be used as a default value in the clients (default: "")
-  -t, --template <string>   Template used for generating API client. Default: "axios"
-  --preferAny               Use "any" type instead of "unknown" (default: false)
-  --skipDeprecated          Skip deprecated operations. When enabled, deprecated operations will be skipped from the generated code (default: false)
-  --servicePrefix <string>  Prefix for service names. Useful when you have multiple APIs and you want to avoid name collisions (default: "")
-  --allowDots <bool>        Determines if dots should be used for serialization object properties
-  --arrayFormat <format>    Determines how arrays should be serialized (choices: "indices", "repeat", "brackets")
-  -h, --help                display help for command
+```bash
+npm install swaggie --save-dev
 ```
 
-Sample CLI usage using Swagger's Pet Store:
+Or install globally to use from anywhere:
 
 ```bash
-swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore.ts
+npm install swaggie -g
 ```
 
-`swaggie` outputs TypeScript that is somehow formatted, but it's far from perfect. You can adjust the generated code by prettifying output using your preferred beautify tool using your repo's styling guidelines. For example involving `prettier` looks like this:
+---
 
-```bash
-swaggie -s $URL -o ./client/petstore.ts && prettier ./client/petstore.ts --write`
-```
+## OpenAPI Version Support
 
-And this can be easily automated (in the `npm` scripts for example)
+Swaggie supports **OpenAPI 3.0 and newer**. OpenAPI 2.0 (Swagger) is not supported.
 
-### Configuration File
+If your backend still produces a 2.0 spec, you have a few options:
 
-Instead of providing all required flags from the command line you can alternatively create a new JSON file where you can fill up all settings.
+- **(Recommended)** Update your backend to generate an OpenAPI 3.0 spec instead
+- Convert your 2.0 spec to 3.0 using [swagger2openapi](https://www.npmjs.com/package/swagger2openapi)
+- Stay on `Swaggie v0.x` if upgrading is not currently possible
 
-Sample configuration looks like this:
+---
 
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/yhnavein/swaggie/master/schema.json",
-  "out": "./src/client/petstore.ts",
-  "src": "https://petstore3.swagger.io/api/v3/openapi.json",
-  "template": "axios",
-  "baseUrl": "/api",
-  "preferAny": true,
-  "servicePrefix": "",
-  "dateFormat": "Date", // "string" | "Date"
-  "nullableStrategy": "ignore", // "ignore" | "include" | "nullableAsOptional"
-  "queryParamsSerialization": {
-    "arrayFormat": "repeat", // "repeat" | "brackets" | "indices"
-    "allowDots": true
-  }
-}
-```
+## Quick Start
 
-### Templates
+### CLI
 
-The following templates are bundled with Swaggie:
+Run Swaggie from the command line:
 
-```
-axios       Default template. Recommended for React / Vue / similar frameworks. Uses axios
-xior        Lightweight and modern alternative to axios. Uses [xior](https://github.com/suhaotian/xior#intro)
-swr-axios   SWR for GET requests with axios as backend
-tsq-xior    TanStack Query for GET requests with xior as backend
-fetch       Barebone fetch API. Recommended for React / Vue / similar frameworks
-ng1         Angular 1 client (this is for the old one)
-ng2         Angular 2+ client (uses HttpClient, InjectionTokens, etc)
+```bash
+swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore.ts
 ```
 
-If you want to use your own template, you can use the path to your template for the `-t` parameter:
+**Available options:**
 
-```bash
-swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore --template ./my-swaggie-template/
+```
+-V, --version             Output the version number
+-c, --config <path>       Path to a JSON configuration file
+-s, --src <url|path>      URL or file path to the OpenAPI spec
+-o, --out <filePath>      Output file path (omit to print to stdout)
+-b, --baseUrl <string>    Default base URL for the generated client (default: "")
+-t, --template <string>   Template to use for code generation (default: "axios")
+    --preferAny           Use "any" instead of "unknown" for untyped values (default: false)
+    --skipDeprecated      Exclude deprecated operations from the output (default: false)
+    --servicePrefix       Prefix for service names — useful when generating multiple APIs
+    --allowDots           Use dot notation to serialize nested object query params
+    --arrayFormat         How arrays are serialized: "indices", "repeat", or "brackets"
+-h, --help                Show help
 ```
 
-## Usage – Integrating into your project
+### Formatting the Output
 
-Let's assume that you have a [PetStore API](http://petstore.swagger.io/) as your REST API and you are developing a client app written in TypeScript that will consume this API.
+Swaggie produces functional TypeScript, but the formatting is not always perfect. It is recommended to pipe the output through a formatter. For example, using Prettier:
 
-Instead of writing any code by hand for fetching particular resources, we will let Swaggie do it for us.
+```bash
+swaggie -s $URL -o ./client/petstore.ts && prettier ./client/petstore.ts --write
+```
+
+This can be added as an `npm` script in your project for easy re-generation.
 
-### Query Parameters Serialization
+---
 
-When it comes to use of query parameters then you might need to adjust the way these parameters will be serialized, as backend server you are using expects them to be in a specific format. Thankfully in Swaggie you can specify how they should be handled. If you won't provide any configuration, then Swaggie will use the defaults values expected in the ASP.NET Core world.
+## Configuration File
 
-For your convenience there are few config examples to achieve different serialization formats for an object `{ "a": { "b": 1 }, "c": [2, 3] }`:
+For anything beyond a one-off run, a configuration file is the cleaner approach. Create a JSON file with your settings and pass it via `-c`:
 
-| Expected Format         | allowDots | arrayFormat |
-| ----------------------- | --------- | ----------- |
-| `?a.b=1&c=2&c=3`        | `true`    | `repeat`    |
-| `?a.b=1&c[]=2&c[]=3`    | `true`    | `brackets`  |
-| `?a.b=1&c[0]=2&c[1]=3`  | `true`    | `indices`   |
-| `?a[b]=1&c=2&c=3`       | `false`   | `repeat`    |
-| `?a[b]=1&c[]=2&c[]=3`   | `false`   | `brackets`  |
-| `?a[b]=1&c[0]=2&c[1]=3` | `false`   | `indices`   |
+```bash
+swaggie -c swaggie.config.json
+```
 
-Once you know what your backend expects, you can adjust the configuration file accordingly: (below are default values)
+**Example configuration:**
 
 ```json
 {
+  "$schema": "https://raw.githubusercontent.com/yhnavein/swaggie/master/schema.json",
+  "src": "https://petstore3.swagger.io/api/v3/openapi.json",
+  "out": "./src/client/petstore.ts",
+  "template": "axios",
+  "baseUrl": "/api",
+  "preferAny": true,
+  "servicePrefix": "",
+  "dateFormat": "Date",
+  "nullableStrategy": "ignore",
   "queryParamsSerialization": {
     "arrayFormat": "repeat",
     "allowDots": true
@@ -163,57 +126,47 @@ Once you know what your backend expects, you can adjust the configuration file a
 }
 ```
 
-### Nullable Strategy
-
-OpenAPI 3.0 allows marking fields as `nullable: true`. Swaggie provides three strategies for translating this into TypeScript, controlled by the `nullableStrategy` option:
-
-| Value                  | Description                                                                        |
-| ---------------------- | ---------------------------------------------------------------------------------- |
-| `"ignore"` (default)   | `nullable: true` is ignored. Types are generated as if `nullable` was not set.     |
-| `"include"`            | `nullable: true` appends `\| null` to the TypeScript type (e.g. `string \| null`). |
-| `"nullableAsOptional"` | `nullable: true` makes the property optional (`?`) instead of adding `\| null`.    |
-
-**Examples** for a schema with `tenant: { type: 'string', nullable: true }` (required):
-
-```typescript
-// nullableStrategy: "ignore"   →  tenant: string;
-// nullableStrategy: "include"  →  tenant: string | null;
-// nullableStrategy: "nullableAsOptional"  →  tenant?: string;
-```
-
-### Code Quality
+The `$schema` field enables autocompletion and inline documentation in most editors.
 
-> Please note that it's **recommended** to pipe Swaggie command to some prettifier like `prettier`, `biome` or `dprint` to make the generated code look not only nice, but also persistent.
-> Because Swaggie relies on a templating engine, whitespaces are generally a mess, so they may change between versions.
+---
 
-**Suggested prettiers**
+## Templates
 
-[prettier](https://prettier.io/) - the most popular one
+Swaggie ships with the following built-in templates:
 
-```bash
-prettier ./FILE_PATH.ts --write
-```
+| Template    | Description                                                                               |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `axios`     | Default. Recommended for React, Vue, and similar frameworks                               |
+| `xior`      | Lightweight modern alternative to axios ([xior](https://github.com/suhaotian/xior#intro)) |
+| `swr-axios` | SWR hooks for GET requests, backed by axios                                               |
+| `tsq-xior`  | TanStack Query hooks for GET requests, backed by xior                                     |
+| `fetch`     | Uses the native browser Fetch API                                                         |
+| `ng1`       | Angular 1 client                                                                          |
+| `ng2`       | Angular 2+ client (uses HttpClient and InjectionTokens)                                   |
 
-[biome](https://biomejs.dev) - the super fast one
+To use a custom template, pass the path to your template directory:
 
 ```bash
-biome check ./FILE_PATH.ts --apply-unsafe
+swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore.ts --template ./my-swaggie-template/
 ```
 
-You are not limited to any of these, but in our examples we will use Prettier. Please remember that these tools needs to be installed first and they need a config file in your project.
+---
 
-### Example
+## Example
 
-Let's run `swaggie` against PetStore API and see what will happen:
+Let's say you're building a TypeScript client for the [PetStore API](https://petstore3.swagger.io). Instead of writing fetch calls by hand, run:
 
 ```bash
 swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./api/petstore.ts && prettier ./api/petstore.ts --write
 ```
 
+Swaggie will generate something like this:
+
 ```typescript
 // ./api/petstore.ts
 
 import Axios, { AxiosPromise } from 'axios';
+
 const axios = Axios.create({
   baseURL: '/api',
   paramsSerializer: (params) =>
@@ -242,27 +195,71 @@ export const petClient = {
 };
 ```
 
-When we have that we can write some domain code and use this auto-generated classes:
+You can then use it directly in your application code:
 
 ```typescript
 // app.ts
 
-import { petClient } from './api/petClient';
+import { petClient } from './api/petstore';
 
 petClient.getPetById(123).then((pet) => console.log('Pet: ', pet));
 ```
 
-If Petstore owners decide to remove method we use, then after running `swaggie` again it will no longer be present in the `petClient` class. This will result in the build error, which is very much appreciated at this stage.
+If the API removes an endpoint you rely on, re-running Swaggie will cause a **compile-time error** — not a runtime surprise for your users.
+
+---
+
+## Advanced Configuration
+
+### Query Parameter Serialization
+
+Different backends expect query parameters in different formats. Swaggie lets you control this via the `queryParamsSerialization` config. The default values match what ASP.NET Core expects.
+
+Here's how the object `{ "a": { "b": 1 }, "c": [2, 3] }` is serialized under each combination:
+
+| Result                  | `allowDots` | `arrayFormat` |
+| ----------------------- | ----------- | ------------- |
+| `?a.b=1&c=2&c=3`        | `true`      | `repeat`      |
+| `?a.b=1&c[]=2&c[]=3`    | `true`      | `brackets`    |
+| `?a.b=1&c[0]=2&c[1]=3`  | `true`      | `indices`     |
+| `?a[b]=1&c=2&c=3`       | `false`     | `repeat`      |
+| `?a[b]=1&c[]=2&c[]=3`   | `false`     | `brackets`    |
+| `?a[b]=1&c[0]=2&c[1]=3` | `false`     | `indices`     |
+
+Once you identify what your backend expects, update your config:
+
+```json
+{
+  "queryParamsSerialization": {
+    "arrayFormat": "repeat",
+    "allowDots": true
+  }
+}
+```
+
+### Nullable Strategy
 
-Without this approach, the error would be spotted by our end-user and he/she would not appreciate it at all!
+OpenAPI 3.0 allows fields to be marked as `nullable: true`. Swaggie gives you three ways to handle this in the generated TypeScript, via the `nullableStrategy` option:
 
-## Other features
+| Value                  | Behavior                                                              |
+| ---------------------- | --------------------------------------------------------------------- |
+| `"ignore"` _(default)_ | `nullable` is ignored — the field is typed as if it were not nullable |
+| `"include"`            | Appends `\| null` to the type (e.g. `string \| null`)                 |
+| `"nullableAsOptional"` | Makes the field optional (`?`) instead of adding `\| null`            |
 
-### Parameter adjustment
+**Example** — given `tenant: { type: 'string', nullable: true }` (required):
 
-In some cases you might want to adjust the parameters globally but without touching the OpenAPI spec. For example, the spec may explicitly define some of parameters as `required`, but you will handle them in the interceptor. In such case, you don't want to define them is every single method. This is where this feature comes in handy.
+```typescript
+// nullableStrategy: "ignore"            →  tenant: string;
+// nullableStrategy: "include"           →  tenant: string | null;
+// nullableStrategy: "nullableAsOptional"  →  tenant?: string;
+```
 
-Example (in the config file):
+### Parameter Modifiers
+
+Sometimes an API spec marks a parameter as required, but your client handles it in an interceptor and you don't want it cluttering every method signature. Parameter modifiers let you override this globally without touching the spec.
+
+**Example:**
 
 ```json
 {
@@ -276,23 +273,37 @@ Example (in the config file):
 }
 ```
 
-This will ensure that `clientId` parameters will never appear in any of the generated methods, and `orgId` will be optional (regardless of what the spec says).
-You can also use `required` value to enforce the parameter to be required, _(but in this case, realistically it would be better to just fix the spec)_.
+- `"ignore"` — the parameter is removed from all generated method signatures
+- `"optional"` — the parameter becomes optional regardless of what the spec says
+- `"required"` — the parameter is always required (generally better to just fix the spec)
+
+### Code Quality
+
+Swaggie's output is functional but not always perfectly formatted, since it uses a templating engine internally. It is strongly recommended to run the output through a formatter to ensure consistent style across regenerations.
+
+**Prettier** (most popular):
+
+```bash
+prettier ./FILE_PATH.ts --write
+```
 
-## Server config
+**Biome** (fast alternative):
 
-You might wonder how to set up server to fully utilize Swaggie's features. For that I've added a `samples/` folder with sample configurations.
+```bash
+biome check ./FILE_PATH.ts --apply-unsafe
+```
 
-[ASP.NET Core + Nswag](./samples/dotnetcore/nswag/README.md)
+Either tool needs to be installed separately and configured for your project.
 
-[ASP.NET Core + Swashbuckle](./samples/dotnetcore/swashbuckle/README.md)
+---
 
-Server is not necessary to use Swaggie. Swaggie cares only about the JSON/yaml file with the Open API spec, but for your development purpose you might want to have a server that can serve this file automatically from the actual endpoints.
+## Using Swaggie Programmatically
 
-## Using Swaggie programmatically
+You can also call Swaggie directly from Node.js/bun/deno/etc:
 
 ```javascript
-const swaggie = require('swaggie');
+import swaggie from 'swaggie';
+
 swaggie
   .genCode({
     src: 'https://petstore3.swagger.io/api/v3/openapi.json',
@@ -309,22 +320,35 @@ function error(e) {
 }
 ```
 
-## Notes
-
-| Supported                                                                      | Not supported                                   |
-| ------------------------------------------------------------------------------ | ----------------------------------------------- |
-| OpenAPI 3, OpenAPI 3.1, OpenAPI 3.2                                            | Swagger, Open API 2.0                           |
-| `allOf`, `oneOf`, `anyOf`, `$ref` to schemas                                   | `not`                                           |
-| Spec formats: `JSON`, `YAML`                                                   | VERY complex query params                       |
-| Extensions: `x-position`, `x-name`, `x-enumNames`, `x-enum-varnames`           | Multiple response types (only one will be used) |
-| Content types: `JSON`, `text`, `multipart/form-data`                           | Multiple request types (only one will be used)  |
-| Content types: `application/x-www-form-urlencoded`, `application/octet-stream` | References to external spec files               |
-| Different types of enum definitions                                            | OpenAPI callbacks                               |
-| Paths inheritance, comments (descriptions), nullable, `["<TYPE>", null]`       | OpenAPI webhooks                                |
-| Getting documents from remote locations or as path reference (local file)      |                                                 |
-| Grouping endpoints by tags + handle gracefully duplicate operation ids         |                                                 |
-
-## Used by
+---
+
+## Server Setup Samples
+
+Swaggie only needs a JSON or YAML OpenAPI spec file — it does not require a running server. However, if you want to see how to configure your backend to expose an OpenAPI spec automatically, check out the sample configurations in the `samples/` folder:
+
+- [ASP.NET Core + NSwag](./samples/dotnetcore/nswag/README.md)
+- [ASP.NET Core + Swashbuckle](./samples/dotnetcore/swashbuckle/README.md)
+
+---
+
+## What's Supported
+
+| Supported                                                                      | Not Supported                                        |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| OpenAPI 3.0, 3.1, 3.2                                                          | Swagger / OpenAPI 2.0                                |
+| `allOf`, `oneOf`, `anyOf`, `$ref`                                              | `not` keyword                                        |
+| Spec formats: JSON, YAML                                                       | Very complex query parameter structures              |
+| Extensions: `x-position`, `x-name`, `x-enumNames`, `x-enum-varnames`           | Multiple response types (only the first is used)     |
+| Content types: JSON, plain text, multipart/form-data                           | Multiple request body types (only the first is used) |
+| Content types: `application/x-www-form-urlencoded`, `application/octet-stream` | References to external spec files                    |
+| Various enum definition styles                                                 | OpenAPI callbacks and webhooks                       |
+| Nullable types, path inheritance, JSDoc descriptions                           |                                                      |
+| Remote URLs and local file paths as spec source                                |                                                      |
+| Grouping by tags, graceful handling of duplicate operation IDs                 |                                                      |
+
+---
+
+## Used By
 
 <div style="display: flex; gap: 1rem;">
 <a href="https://www.britishcouncil.org"><img alt="British Council" src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/BritishCouncil.png/320px-BritishCouncil.png" style="height: 50px;" /></a>

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import type { OpenAPIV3 } from 'openapi-types';
-import type { ClientOptions, FullAppOptions } from '../src/types';
+import type { ClientOptions, FullAppOptions } from './types';
 
-/** Runs whole code generation process. @returns generated code */
-export declare function runCodeGenerator(options: FullAppOptions): Promise<string>;
-/** Validates if the spec is correct and if is supported */
-export declare function verifySpec(spec: OpenAPIV3.Document): Promise<OpenAPIV3.Document>;
-export declare function applyConfigFile(options: FullAppOptions): Promise<ClientOptions>;
+export type CodeGenResult = [string, AppOptions];
+
+/**
+ * Runs the whole code generation process @returns `CodeGenResult`
+ **/
+export declare function runCodeGenerator(options: Partial<FullAppOptions>): Promise<CodeGenResult>;

package/dist/utils/documentLoader.js

@@ -1,6 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }var _nodefs = require('node:fs'); var _nodefs2 = _interopRequireDefault(_nodefs);
 var _yaml = require('yaml');
 
+var _refResolver = require('./refResolver');
 
 /**
  * Function that loads an OpenAPI document from a path or URL
@@ -32,10 +33,15 @@ async function loadFromUrl(url) {
   return parseFileContents(contents, url);
 }
 
-function readLocalFile(filePath) {
-  return new Promise((res, rej) =>
-    _nodefs2.default.readFile(filePath, 'utf8', (err, contents) => (err ? rej(err) : res(contents)))
-  ).then((contents) => parseFileContents(contents, filePath));
+async function readLocalFile(filePath) {
+  const contents = await new Promise((res, rej) =>
+    _nodefs2.default.readFile(filePath, 'utf8', (err, loadedContents) =>
+      err ? rej(err) : res(loadedContents)
+    )
+  );
+  const spec = parseFileContents(contents , filePath) ;
+
+  return _refResolver.resolveExternalFileRefs.call(void 0, spec, filePath);
 }
 
 function parseFileContents(contents, path) {

package/dist/utils/index.js

@@ -1,3 +1,4 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _createStarExport(obj) { Object.keys(obj) .filter((key) => key !== "default" && key !== "__esModule") .forEach((key) => { if (exports.hasOwnProperty(key)) { return; } Object.defineProperty(exports, key, {enumerable: true, configurable: true, get: () => obj[key]}); }); }var _utils = require('./utils'); _createStarExport(_utils);
 var _documentLoader = require('./documentLoader'); _createStarExport(_documentLoader);
+var _refResolver = require('./refResolver'); _createStarExport(_refResolver);
 var _templateManager = require('./templateManager'); _createStarExport(_templateManager);

package/dist/utils/refResolver.js

@@ -0,0 +1,309 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }var _promises = require('node:fs/promises'); var _promises2 = _interopRequireDefault(_promises);
+var _nodepath = require('node:path'); var _nodepath2 = _interopRequireDefault(_nodepath);
+var _yaml = require('yaml');
+
+
+
+
+
+
+
+
+const SUPPORTED_COMPONENT_SECTIONS = new Set([
+  'schemas',
+  'parameters',
+  'requestBodies',
+  'responses',
+]);
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * Resolves external file refs into local component refs.
+ * For now we only support local file refs (no http/https) and component targets.
+ */
+ async function resolveExternalFileRefs(
+  spec,
+  rootSpecPath
+) {
+  const resolvedRootPath = _nodepath2.default.resolve(rootSpecPath);
+  const context = {
+    rootSpec: spec,
+    rootSpecPath: resolvedRootPath,
+    docCache: new Map(),
+    importedRefs: new Map(),
+    resolvingRefs: new Set(),
+  };
+
+  await rewriteRefsInNode(spec, resolvedRootPath, context);
+
+  return spec;
+} exports.resolveExternalFileRefs = resolveExternalFileRefs;
+
+async function rewriteRefsInNode(node, currentFilePath, context) {
+  if (!node) {
+    return;
+  }
+
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      await rewriteRefsInNode(item, currentFilePath, context);
+    }
+    return;
+  }
+
+  if (typeof node !== 'object') {
+    return;
+  }
+
+  const record = node ;
+
+  if (typeof record.$ref === 'string') {
+    const resolved = await resolveRef(record.$ref, currentFilePath, context);
+    if (resolved.type === 'ref') {
+      record.$ref = resolved.value;
+    } else if (Object.keys(record).length === 1) {
+      for (const key of Object.keys(record)) {
+        delete record[key];
+      }
+      Object.assign(record, resolved.value );
+    }
+  }
+
+  const values = Object.values(record);
+  for (const value of values) {
+    await rewriteRefsInNode(value, currentFilePath, context);
+  }
+}
+
+async function resolveRef(
+  rawRef,
+  currentFilePath,
+  context
+) {
+  if (rawRef.startsWith('#/')) {
+    if (_nodepath2.default.resolve(currentFilePath) === context.rootSpecPath) {
+      return { type: 'ref', value: rawRef };
+    }
+
+    return importRefFromFile(_nodepath2.default.resolve(currentFilePath), rawRef, rawRef, context);
+  }
+
+  if (/^https?:\/\//i.test(rawRef)) {
+    throw new Error(`External HTTP refs are not supported: '${rawRef}'`);
+  }
+
+  const [rawFilePath, fragment] = rawRef.split('#');
+  if (!rawFilePath) {
+    throw new Error(`Unsupported $ref format: '${rawRef}'`);
+  }
+
+  if (!fragment) {
+    throw new Error(
+      `External refs must include a JSON pointer fragment: '${rawRef}'`
+    );
+  }
+
+  if (!fragment.startsWith('/')) {
+    throw new Error(`Unsupported $ref pointer format: '${rawRef}'`);
+  }
+
+  const resolvedPath = _nodepath2.default.resolve(_nodepath2.default.dirname(currentFilePath), rawFilePath);
+  const pointer = `#${fragment}`;
+
+  return importRefFromFile(resolvedPath, pointer, rawRef, context);
+}
+
+async function importRefFromFile(
+  sourceFilePath,
+  pointer,
+  rawRef,
+  context
+) {
+  const targetInfo = parseImportTarget(pointer);
+  const target = await getValueByPointer(sourceFilePath, pointer, context);
+  const importKey = `${sourceFilePath}${pointer}`;
+
+  if (!targetInfo) {
+    if (context.resolvingRefs.has(importKey)) {
+      throw new Error(
+        `Circular non-component external ref is not supported: '${rawRef}'`
+      );
+    }
+
+    const targetCopy = structuredClone(target);
+    context.resolvingRefs.add(importKey);
+    await rewriteRefsInNode(targetCopy, sourceFilePath, context);
+    context.resolvingRefs.delete(importKey);
+
+    return { type: 'inline', value: targetCopy };
+  }
+  const existingRef = context.importedRefs.get(importKey);
+  if (existingRef) {
+    return { type: 'ref', value: existingRef };
+  }
+
+  const section = targetInfo.section;
+  const name = targetInfo.name;
+  const targetCopy = structuredClone(target);
+  const alias = getOrCreateComponentAlias(section, name, sourceFilePath, context);
+  const localRef = `#/components/${section}/${alias}`;
+
+  context.importedRefs.set(importKey, localRef);
+
+  const sectionMap = ensureComponentSection(context.rootSpec, section);
+  sectionMap[alias] = targetCopy;
+
+  context.resolvingRefs.add(importKey);
+  await rewriteRefsInNode(targetCopy, sourceFilePath, context);
+  context.resolvingRefs.delete(importKey);
+
+  return { type: 'ref', value: localRef };
+}
+
+function parseImportTarget(pointer) {
+  const parts = pointer
+    .replace(/^#\//, '')
+    .split('/')
+    .map(unescapePointerSegment);
+
+  if (parts.length === 2) {
+    const [legacySection, name] = parts;
+    if (legacySection === 'parameters') {
+      return { section: 'parameters', name };
+    }
+    if (legacySection === 'responses') {
+      return { section: 'responses', name };
+    }
+    if (legacySection === 'requestBodies') {
+      return { section: 'requestBodies', name };
+    }
+    if (legacySection === 'definitions') {
+      return { section: 'schemas', name };
+    }
+  }
+
+  if (parts.length !== 3 || parts[0] !== 'components') {
+    return null;
+  }
+
+  const section = parts[1] ;
+  const name = parts[2];
+
+  if (!SUPPORTED_COMPONENT_SECTIONS.has(section)) {
+    return null;
+  }
+
+  if (!name) {
+    return null;
+  }
+
+  return { section, name };
+}
+
+function ensureComponentSection(
+  spec,
+  section
+) {
+  if (!spec.components) {
+    spec.components = {};
+  }
+
+  if (!spec.components[section]) {
+    spec.components[section] = {};
+  }
+
+  return spec.components[section] ;
+}
+
+function getOrCreateComponentAlias(
+  section,
+  originalName,
+  sourceFilePath,
+  context
+) {
+  const sectionMap = ensureComponentSection(context.rootSpec, section);
+
+  if (!sectionMap[originalName]) {
+    return originalName;
+  }
+
+  const suffix = shortHash(sourceFilePath);
+  let candidate = `${originalName}__${suffix}`;
+  let inc = 2;
+
+  while (sectionMap[candidate]) {
+    candidate = `${originalName}__${suffix}_${inc}`;
+    inc += 1;
+  }
+
+  return candidate;
+}
+
+async function getValueByPointer(filePath, pointer, context) {
+  const doc = await loadDocument(filePath, context);
+  const parts = pointer
+    .replace(/^#\//, '')
+    .split('/')
+    .map(unescapePointerSegment);
+
+  let current = doc;
+  for (const part of parts) {
+    if (!current || typeof current !== 'object' || !(part in current)) {
+      throw new Error(`Could not resolve ref pointer '${pointer}' in '${filePath}'`);
+    }
+
+    current = current[part];
+  }
+
+  return current;
+}
+
+async function loadDocument(filePath, context) {
+  const absPath = _nodepath2.default.resolve(filePath);
+  const cached = context.docCache.get(absPath);
+  if (cached) {
+    return cached;
+  }
+
+  const contents = await _promises2.default.readFile(absPath, 'utf8');
+  const parsed = parseFileContents(contents, absPath);
+  context.docCache.set(absPath, parsed);
+  return parsed;
+}
+
+function parseFileContents(contents, filePath) {
+  if (/.ya?ml$/i.test(filePath)) {
+    return _yaml.parse.call(void 0, contents);
+  }
+
+  if (/.json$/i.test(filePath)) {
+    return JSON.parse(contents);
+  }
+
+  const firstChar = contents.trimStart()[0];
+  return firstChar === '{' ? JSON.parse(contents) : _yaml.parse.call(void 0, contents);
+}
+
+function unescapePointerSegment(segment) {
+  return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+function shortHash(input) {
+  let hash = 0;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash * 31 + input.charCodeAt(i)) >>> 0;
+  }
+
+  return hash.toString(36);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "swaggie",
-  "version": "1.6.0",
-  "description": "Generate TypeScript REST client code from an OpenAPI spec",
+  "version": "1.7.0-beta.1",
+  "description": "Generate a fully typed TypeScript API client from your OpenAPI 3 spec",
   "author": {
     "name": "Piotr Dabrowski",
     "url": "https://github.com/yhnavein"
@@ -35,7 +35,10 @@
   "keywords": [
     "swagger",
     "openapi",
+    "oapi",
     "openapi 3.0",
+    "openapi 3.1",
+    "openapi 3.2",
     "rest",
     "rest client",
     "fetch",
@@ -53,10 +56,10 @@
     "commander": "^14.0.3",
     "eta": "^4.5.1",
     "yaml": "^2.8.2",
-    "nanocolors": "^0.2.0"
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "bun-types": "1.3.9",
+    "bun-types": "1.3.10",
     "openapi-types": "^12.1.3",
     "sucrase": "3.35.1",
     "typescript": "5.9.3"