{"id":49873350,"url":"https://github.com/stacksjs/ts-open-api","last_synced_at":"2026-05-15T11:05:15.689Z","repository":{"id":323415301,"uuid":"1093140549","full_name":"stacksjs/ts-open-api","owner":"stacksjs","description":"OpenAPI TypeScript automations.","archived":false,"fork":false,"pushed_at":"2026-05-14T06:52:36.000Z","size":22520,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T08:37:20.372Z","etag":null,"topics":["geneator","openapi","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacksjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["stacksjs","chrisbbreuer"],"open_collective":"stacksjs"}},"created_at":"2025-11-10T00:47:54.000Z","updated_at":"2026-05-12T09:35:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stacksjs/ts-open-api","commit_stats":null,"previous_names":["stacksjs/ts-open-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stacksjs/ts-open-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fts-open-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fts-open-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fts-open-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fts-open-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacksjs","download_url":"https://codeload.github.com/stacksjs/ts-open-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacksjs%2Fts-open-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33064661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geneator","openapi","typescript"],"created_at":"2026-05-15T11:05:14.434Z","updated_at":"2026-05-15T11:05:15.684Z","avatar_url":"https://github.com/stacksjs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/stacksjs","https://github.com/sponsors/chrisbbreuer","https://opencollective.com/stacksjs"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\".github/art/cover.jpg\" alt=\"Social Card of this repo\"\u003e\u003c/p\u003e\n\n[![npm version](https://img.shields.io/npm/v/ts-open-api?style=flat-square)](https://npmjs.com/package/ts-open-api)\n[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/stacksjs/ts-open-api/ci.yml?style=flat-square\u0026branch=main)](https://github.com/stacksjs/ts-open-api/actions?query=workflow%3Aci)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n# ts-open-api\n\nA blazingly fast, native OpenAPI to TypeScript type generator built with Bun. Generate TypeScript types from OpenAPI 3.0 schemas with zero runtime overhead.\n\n## Why ts-open-api\n\n- ⚡️ **Lightning Fast** - Built with Bun for maximum performance\n- 🎯 **Zero Runtime** - Pure TypeScript types with no runtime dependencies\n- 🔧 **Highly Configurable** - Extensive options for customizing output\n- 📝 **JSDoc Support** - Generate rich documentation from your OpenAPI schemas\n- 🎨 **Transform API** - Customize type generation with transform hooks\n- 🧪 **Well Tested** - Comprehensive test suite with 26+ test cases\n- 🚀 **Native Implementation** - No external dependencies for type generation\n\n## Features\n\n- ✅ Full OpenAPI 3.0 \u0026 3.1 support\n- ✅ Generate types from local or remote schemas\n- ✅ Support for all schema types (objects, arrays, enums, unions, etc.)\n- ✅ Schema composition (allOf, anyOf, oneOf)\n- ✅ Reference resolution ($ref)\n- ✅ Path parameters, query parameters, and headers\n- ✅ Request bodies and responses\n- ✅ JSDoc comments with descriptions and examples\n- ✅ Readonly/immutable types\n- ✅ Custom type transformations\n- ✅ Alphabetical sorting\n- ✅ CLI and programmatic API\n\n## Installation\n\n```bash\n# Using bun\nbun add -D ts-open-api\n\n# Using npm\nnpm install -D ts-open-api\n\n# Using pnpm\npnpm add -D ts-open-api\n\n# Using yarn\nyarn add -D ts-open-api\n```\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Generate types from a local OpenAPI schema\nopen-api ./openapi.json --output ./api-types.ts\n\n# Generate from a remote schema\nopen-api https://api.example.com/openapi.json --output ./api-types.ts\n\n# With options\nopen-api ./openapi.json \\\n  --output ./api-types.ts \\\n  --alphabetize \\\n  --immutable \\\n  --include-descriptions\n```\n\n### Programmatic Usage\n\n```typescript\nimport { generateTypes } from 'ts-open-api'\n\nawait generateTypes({\n  input: './openapi.json',\n  output: './api-types.ts',\n  alphabetize: true,\n  immutable: true,\n  includeDescriptions: true,\n})\n```\n\n### Node.js API\n\n```typescript\nimport { OpenAPITypeScriptGenerator } from 'ts-open-api'\nimport type { OpenAPISchema } from 'ts-open-api'\n\nconst schema: OpenAPISchema = {\n  openapi: '3.0.0',\n  info: { title: 'My API', version: '1.0.0' },\n  paths: {\n    '/users': {\n      get: {\n        responses: {\n          '200': {\n            description: 'Success',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'array',\n                  items: { $ref: '#/components/schemas/User' },\n                },\n              },\n            },\n          },\n        },\n      },\n    },\n  },\n  components: {\n    schemas: {\n      User: {\n        type: 'object',\n        required: ['id', 'name'],\n        properties: {\n          id: { type: 'string' },\n          name: { type: 'string' },\n          email: { type: 'string' },\n        },\n      },\n    },\n  },\n}\n\nconst generator = new OpenAPITypeScriptGenerator(schema, {\n  input: '',\n  output: '',\n  alphabetize: true,\n})\n\nconst typescript = generator.generate()\nconsole.log(typescript)\n```\n\n## CLI Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--output \u003cpath\u003e` | Output file path | `./api-types.ts` |\n| `--alphabetize` | Sort types alphabetically | `false` |\n| `--immutable` | Generate readonly properties | `false` |\n| `--silent` | Suppress console output | `false` |\n| `--export-type` | Use `export type` instead of `export interface` | `false` |\n| `--default-non-nullable` | Treat schema objects as non-nullable by default | `false` |\n| `--additional-properties` | Allow arbitrary properties via index signature | `false` |\n| `--path-params-as-types` | Generate path params as string literal types | `false` |\n| `--support-array-length` | Support array length validation in types | `false` |\n| `--no-header` | Disable header comment | `false` |\n| `--include-descriptions` | Include descriptions as JSDoc comments | `false` |\n| `--include-examples` | Include examples in JSDoc comments | `false` |\n\n## Programmatic API Options\n\nAll CLI options are available in the programmatic API, plus additional advanced options:\n\n```typescript\ninterface GeneratorOptions {\n  input: string\n  output: string\n\n  // Type generation options\n  exportType?: boolean\n  alphabetize?: boolean\n  immutable?: boolean\n  additionalProperties?: boolean\n  defaultNonNullable?: boolean\n  pathParamsAsTypes?: boolean\n  supportArrayLength?: boolean\n\n  // Documentation options\n  includeDescriptions?: boolean\n  includeExamples?: boolean\n\n  // Header options\n  header?: boolean\n  headerComment?: string\n\n  // Output options\n  silent?: boolean\n\n  // Advanced options\n  transform?: (schema: SchemaObject) =\u003e SchemaObject\n  postTransform?: (typescript: string) =\u003e string\n  inject?: string\n}\n```\n\n## Advanced Usage\n\n### Custom Transformations\n\nTransform schemas before type generation:\n\n```typescript\nawait generateTypes({\n  input: './openapi.json',\n  output: './api-types.ts',\n  transform: (schema) =\u003e {\n    // Add custom logic to transform schemas\n    if (schema.type === 'string' \u0026\u0026 schema.format === 'date-time') {\n      // Convert all date-time strings to Date types\n      return { ...schema, type: 'string', tsType: 'Date' }\n    }\n    return schema\n  },\n})\n```\n\n### Post-Processing Generated Types\n\nModify the generated TypeScript code:\n\n```typescript\nawait generateTypes({\n  input: './openapi.json',\n  output: './api-types.ts',\n  postTransform: (typescript) =\u003e {\n    // Add custom imports or modify generated code\n    return `import type { CustomType } from './custom'\\n\\n${typescript}`\n  },\n})\n```\n\n### Inject Custom Types\n\nAdd custom type definitions at the beginning of the file:\n\n```typescript\nawait generateTypes({\n  input: './openapi.json',\n  output: './api-types.ts',\n  inject: `\n// Custom utility types\ntype Nullable\u003cT\u003e = T | null\ntype Optional\u003cT\u003e = T | undefined\n`,\n})\n```\n\n### Custom Header\n\nReplace the default header comment:\n\n```typescript\nawait generateTypes({\n  input: './openapi.json',\n  output: './api-types.ts',\n  headerComment: `/**\n\n * Custom API Types\n * Generated on ${new Date().toISOString()}\n * DO NOT EDIT MANUALLY\n\n */`,\n})\n```\n\n## Examples\n\n### Generate Immutable Types with Descriptions\n\n```bash\nopen-api ./openapi.json \\\n  --output ./api-types.ts \\\n  --immutable \\\n  --include-descriptions \\\n  --include-examples\n```\n\nOutput:\n\n```typescript\nexport interface User {\n  /** The unique identifier for the user */\n  readonly \"id\": string\n  /**\n\n   * The user's full name\n   * @example \"John Doe\"\n\n   */\n  readonly \"name\": string\n  /** The user's email address */\n  readonly \"email\"?: string\n}\n```\n\n### Generate Alphabetized Types\n\n```bash\nopen-api ./openapi.json --output ./api-types.ts --alphabetize\n```\n\n### Programmatic Generation with All Options\n\n```typescript\nimport { generateTypes } from 'ts-open-api'\n\nawait generateTypes({\n  input: './openapi.json',\n  output: './api-types.ts',\n  alphabetize: true,\n  immutable: true,\n  includeDescriptions: true,\n  includeExamples: true,\n  exportType: true,\n  transform: (schema) =\u003e {\n    // Custom transformations\n    return schema\n  },\n  postTransform: (ts) =\u003e {\n    // Post-process generated TypeScript\n    return ts\n  },\n})\n```\n\n## Integration with Build Tools\n\n### Package.json Scripts\n\n```json\n{\n  \"scripts\": {\n    \"generate-types\": \"open-api ./openapi.json --output ./src/api-types.ts\",\n    \"generate:watch\": \"open-api ./openapi.json --output ./src/api-types.ts --watch\",\n    \"prebuild\": \"bun run generate-types\"\n  }\n}\n```\n\n### With Bun\n\n```typescript\n// build.ts\nimport { generateTypes } from 'ts-open-api'\n\n// Generate types before building\nawait generateTypes({\n  input: './api/openapi.json',\n  output: './src/generated/api-types.ts',\n  alphabetize: true,\n})\n\n// Continue with your build process\nawait Bun.build({\n  entrypoints: ['./src/index.ts'],\n  outdir: './dist',\n})\n```\n\n## Comparison with openapi-typescript\n\n| Feature | ts-open-api | openapi-typescript |\n|---------|-------------|-------------------|\n| Runtime | Bun (faster) | Node.js |\n| Dependencies | Zero for generation | Several |\n| OpenAPI 3.0 | ✅ | ✅ |\n| OpenAPI 3.1 | ✅ | ✅ |\n| Transform API | ✅ | ✅ |\n| JSDoc Support | ✅ | ✅ |\n| Immutable Types | ✅ | ✅ |\n| Alphabetization | ✅ | ❌ |\n| Path Params | ✅ | ✅ |\n| Native Code | ✅ | ❌ |\n| Type Safety | ✅ | ✅ |\n\n## Testing\n\n```bash\nbun test\n```\n\nThe project includes comprehensive tests covering:\n\n- Basic schema types (string, number, boolean, array)\n- Object types with properties\n- Nested objects\n- Enum types\n- Nullable types\n- Composition types (allOf, anyOf, oneOf)\n- Reference resolution\n- Path operations\n- Parameters and request bodies\n\n## TypeScript Configuration\n\nFor best results, use these TypeScript settings:\n\n```json\n{\n  \"compilerOptions\": {\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"noUncheckedIndexedAccess\": true,\n    \"strict\": true\n  }\n}\n```\n\n## Changelog\n\nPlease see our [releases](https://github.com/stacksjs/ts-open-api/releases) page for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.\n\n## Community\n\nFor help, discussion about best practices, or any other conversation that would benefit from being searchable:\n\n[Discussions on GitHub](https://github.com/stacksjs/ts-open-api/discussions)\n\nFor casual chit-chat with others using this package:\n\n[Join the Stacks Discord Server](https://discord.gg/stacksjs)\n\n## Postcardware\n\n“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.\n\nOur address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎\n\n## Sponsors\n\nWe would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.\n\n- [JetBrains](https://www.jetbrains.com/)\n- [The Solana Foundation](https://solana.com/)\n\n## License\n\nThe MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.\n\nMade with 💙\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacksjs%2Fts-open-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacksjs%2Fts-open-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacksjs%2Fts-open-api/lists"}