npm package: @pinta365/openapi-typegen
Description: Generate TypeScript types from OpenAPI 2 (Swagger) and OpenAPI 3.x specs
Latest version: 0.0.3

# @pinta365/openapi-typegen

Generate TypeScript types from OpenAPI 2 (Swagger) and OpenAPI 3.x specs. Loads from URL, file path, or object; resolves internal and external
`$ref`s; outputs interfaces and type aliases.

## Usage

Pass a URL, file path, or parsed spec; use `output` with any of them to write the result to a file (or directory when using `split`).

```ts
import { generateTypes } from "@pinta365/openapi-typegen";

// From URL (string)
const source = await generateTypes("https://api.example.com/openapi.json");
// From file path (string)
const fromFile = await generateTypes("references/openapi.json", { output: "api.d.ts" });
// From parsed spec object
const fromObject = await generateTypes({ openapi: "3.0.0", components: { schemas: { ... } } });
```

## API

### `generateTypes(spec, options?)`

Returns a `Promise<string>` of the generated TypeScript source. Optionally writes to a file (or directory when `split` is set) when `output` is set.

- **`spec`** (`SpecInput`): URL string, file path string, `URL` instance, or parsed OpenAPI/Swagger object (OpenAPI 2 or 3.x).
- **`options`** (`GenerateOptions`): Optional. See below.

### Options

| Option                     | Type                                                        | Default                        | Description                                                                                                             |
| -------------------------- | ----------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **`resolver`**             | `(url: string) => Promise<unknown>`                         | `fetch`                        | Resolver for external `$ref` URLs. Receives the URL, returns parsed JSON.                                               |
| **`output`**               | `string`                                                    | —                              | If set, generated TypeScript is written here: file path (single file) or directory path (when `split` is set).          |
| **`split`**                | `"tag"` \| `"path"`                                         | —                              | When set, split types into multiple files by operation tag or path segment; requires `output` (directory).              |
| **`propertyNaming`**       | `"camel"` \| `"preserve"`                                   | `"camel"`                      | Property names in generated types: camelCase or preserve spec as-is.                                                    |
| **`indent`**               | `{ useTabs: true }` \| `{ useTabs: false; width?: number }` | `{ useTabs: false, width: 4 }` | Indentation: one tab per level, or `width` spaces per level (default 4).                                                |
| **`includeHeader`**        | `boolean`                                                   | `true`                         | Whether to emit a file header comment.                                                                                  |
| **`headerComment`**        | `string`                                                    | —                              | Custom header text when `includeHeader` is true. Multi-line strings are emitted as-is.                                  |
| **`sourceLabel`**          | `string`                                                    | (auto from spec)               | Label shown in the default header as “Source file: …”. Set automatically when `spec` is a string or URL.                |
| **`logLevel`**             | `"basic"` \| `"verbose"`                                    | `"basic"`                      | Log level for warnings: basic = short messages; verbose = full details (e.g. all types emitted in multiple files).      |
| **`includeEndpointHints`** | `boolean`                                                   | `true`                         | When true (default), add JSDoc “Used by: METHOD /path” on types referenced by path operations. Set to false to disable. |

**Splitting output**

When `split` is set, pass a directory path as `output`. Types are grouped into multiple files; shared types go to `common.ts`, and an `index.ts`
re-exports everything. Use `split: "tag"` to group by OpenAPI operation tags (e.g. one file per tag like “Daily Activity Routes”). Use `split: "path"`
to group by the first path segment (e.g. `/v2/usercollection/...` → `usercollection.ts`). Types referenced by more than one group are placed in
`common.ts`.

**Default header** (when `includeHeader` is true and `headerComment` is not set):

- Tool name: `@pinta365/openapi-typegen`
- Generated-at timestamp (ISO)
- “Source file:” line when `sourceLabel` is set
- “DO NOT EDIT THIS FILE MANUALLY”

## Behavior

- **OpenAPI 2**: Uses `definitions`; external `$ref` URLs are fetched and merged (including docs that use a `definitions` or `components.schemas`
  wrapper).
- **OpenAPI 3.x**: Uses `components.schemas`; external `$ref` URLs are fetched and merged the same way.
- **External refs**: Both specs support `$ref` to full URLs (e.g. `https://example.com/schemas.json#/Thing`). The library fetches those documents and
  resolves refs recursively; use a custom `resolver` when you need to serve from disk or a different source.
- Type names are PascalCase; property names follow `propertyNaming`. Descriptions and titles become JSDoc (single-line or starred-block for
  multi-line).