{"id":14155670,"url":"https://github.com/nearform/openapi-transformer-toolkit","last_synced_at":"2025-07-11T01:09:24.164Z","repository":{"id":160895890,"uuid":"632820443","full_name":"nearform/openapi-transformer-toolkit","owner":"nearform","description":"Automate design-first API workflows by generating schemas and types from OpenAPI specs.","archived":false,"fork":false,"pushed_at":"2025-07-08T03:07:36.000Z","size":2952,"stargazers_count":22,"open_issues_count":8,"forks_count":4,"subscribers_count":45,"default_branch":"master","last_synced_at":"2025-07-08T03:41:24.597Z","etag":null,"topics":["json-schema","npm","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nearform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-26T07:45:06.000Z","updated_at":"2025-07-08T03:07:37.000Z","dependencies_parsed_at":"2023-12-25T23:23:51.183Z","dependency_job_id":"d6561d26-e4da-4136-b0dc-e6fdd4f7b62c","html_url":"https://github.com/nearform/openapi-transformer-toolkit","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/nearform/openapi-transformer-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearform%2Fopenapi-transformer-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearform%2Fopenapi-transformer-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearform%2Fopenapi-transformer-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearform%2Fopenapi-transformer-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nearform","download_url":"https://codeload.github.com/nearform/openapi-transformer-toolkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearform%2Fopenapi-transformer-toolkit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264211063,"owners_count":23573418,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["json-schema","npm","openapi","typescript"],"created_at":"2024-08-17T08:04:51.122Z","updated_at":"2025-07-11T01:09:24.148Z","avatar_url":"https://github.com/nearform.png","language":"TypeScript","funding_links":[],"categories":["typescript"],"sub_categories":[],"readme":"# OpenAPI Transformer Toolkit\n\nEffortlessly automate your API design-first development workflow by generating [JSON schemas](https://json-schema.org/) and [TypeScript types](https://www.typescriptlang.org/) from an [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0).\n\n## Table of Contents\n\n* [Installation](#installation)\n* [CLI](#cli)\n  * [Create JSON Schema From OpenAPI Definitions](#create-json-schema-from-openapi-definitions)\n    * [Usage](#usage)\n    * [Example](#example)\n    * [Options](#options)\n  * [Generate TypeScript types from OpenAPI Defintions](#generate-typescript-types-from-openapi-defintions)\n    * [Usage](#usage-1)\n    * [Example](#example-1)\n    * [Options](#options-1)\n  * [Generate TypeScript types from JSON schemas](#generate-typescript-types-from-json-schemas)\n    * [Usage](#usage-2)\n    * [Example](#example-2)\n    * [Options](#options-2)\n  * [Create TypeScript JSON Schema From OpenAPI Definitions](#create-typescript-json-schema-from-openapi-definitions)\n    * [Usage](#usage-3)\n    * [Example](#example-3)\n    * [Options](#options-3)\n* [Programmatic Usage](#programmatic-usage)\n  * [Generate JSON Schemas from OpenAPI](#generate-json-schemas-from-openapi)\n  * [Generate TypeScript Types from OpenAPI](#generate-typescript-types-from-openapi)\n  * [Generate TypeScript Types from JSON Schemas](#generate-typescript-types-from-json-schemas-1)\n  * [Generate TypeScript exported JSON Schemas from OpenAPI](#generate-typescript-exported-json-schemas-from-openapi)\n* [Example](#example-4)\n* [Additional Configuration](#additional-configuration)\n\n## Installation\n\nYou can install the package with npm (or another package manager):\n\n```sh\n$ npm install openapi-transformer-toolkit\n```\n\nIf you want to install it globally, you can provide the `-g` flag.\n\nAlternatively, you can run the CLI using `npx`:\n\n```sh\n$ npx openapi-transformer-toolkit [command] [options]\n```\n\n## CLI\n\nFor easier usage, the package includes the `openapi-transformer-toolkit` executable you can use from your CLI.\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### Create JSON Schema From OpenAPI Definitions\n\n\u003c/summary\u003e\n\nUsing the `oas2json` command you can create JSON schema records from OpenAPI definitions.\n\n#### Usage\n\n```sh\nopenapi-transformer-toolkit oas2json [options]\n```\n\n#### Example\n\n```sh\n$ openapi-transformer-toolkit oas2json -i ./openapi.yml -o ./schemas -p paths\n```\n\n#### Options\n\n```\n-i, --input \u003cstring\u003e       Specify the path to the OpenAPI file\n-o, --output \u003cstring\u003e      Specify the path to the folder where you wish to output the schemas\n-p, --properties \u003cstring\u003e  Specify the properties/definitions in the OpenAPI file to convert in a comma-separated list (optional)\n-h, --help                 Display help for command\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### Generate TypeScript types from OpenAPI Defintions\n\n\u003c/summary\u003e\n\nUsing the `oas2ts` command you can create TypeScript types from your OpenAPI definitions.\n\n#### Usage\n\n```sh\nopenapi-transformer-toolkit oas2ts [options]\n```\n\n#### Example\n\n```sh\n$ openapi-transformer-toolkit oas2ts -i ./openapi.yml -o ./types\n```\n\n```sh\n$ openapi-transformer-toolkit oas2ts -i ./openapi.yml -o ./types -c ./config.json\n```\n\n#### Options\n\n```\n-i, --input \u003cstring\u003e     Path to the OpenAPI file\n-o, --output \u003cstring\u003e    Path to the folder where to output the TypeScript types\n-c, --config \u003cstring\u003e    Path to the JSON/JS config file\n-h, --help               Display help for command\n```\n\nSee [Additional Configuration](#additional-configuration) for the `-c, --config` option.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### Generate TypeScript types from JSON schemas\n\n\u003c/summary\u003e\n\nUsing the `json2ts` command you can create TypeScript types from your JSON Schema definitions.\n\n#### Usage\n\n```sh\nopenapi-transformer-toolkit json2ts [options]\n```\n\n#### Example\n\n```sh\n$ openapi-transformer-toolkit json2ts -i ./schemas -o ./types\n```\n\n```sh\n$ openapi-transformer-toolkit json2ts -i ./schemas -o ./types -c ./config.json\n```\n\n#### Options\n\n```\n-i, --input \u003cstring\u003e        Path to the JSON schemas folder\n-o, --output \u003cstring\u003e       Path to the folder where to output the TS files\n-c, --config \u003cstring\u003e       Path to the JSON/JS config file\n-h, --help                  Display help for command\n```\n\nSee [Additional Configuration](#additional-configuration) for the `-c, --config` option.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### Create TypeScript JSON Schema From OpenAPI Definitions\n\n\u003c/summary\u003e\n\nUsing the `oas2tson` command you can create Typescript exported JSON schema records from OpenAPI definitions.\n\n#### Usage\n\n```sh\nopenapi-transformer-toolkit oas2tson [options]\n```\n\n#### Example\n\n```sh\n$ openapi-transformer-toolkit oas2tson -i ./openapi.yml -o ./schemas -p paths\n```\n\n#### Options\n\n```\n-i, --input \u003cstring\u003e       Specify the path to the OpenAPI file\n-o, --output \u003cstring\u003e      Specify the path to the folder where you wish to output the schemas\n-p, --properties \u003cstring\u003e  Specify the properties/definitions in the OpenAPI file to convert in a comma-separated list (optional)\n-h, --help                 Display help for command\n```\n\n\u003c/details\u003e\n\n## Programmatic Usage\n\nYou can also use the package programmatically by importing the necessary functions:\n\n```javascript\nimport { oas2json, oas2ts, json2ts, oas2tson } from 'openapi-transformer-toolkit'\n```\n\n### Generate JSON Schemas from OpenAPI\n\nTo generate JSON schemas from your OpenAPI specification, provide the path to the OpenAPI file and the output directory for the generated schemas:\n\n```javascript\nconst openAPIPath = 'path/to/openapi.yml'\nconst schemasPath = 'path/to/output/schemas'\nconst propertiesToConvert = 'paths'\n\noas2json(openAPIPath, schemasPath, propertiesToConvert)\n```\n\n### Generate TypeScript Types from OpenAPI\n\nTo generate TypeScript types from the OpenAPI specification, provide the path to the OpenAPI file and the output directory for the TypeScript types. Optionally, the third parameter can contain [configuration options](#additional-configuration)\n\n```javascript\nconst openAPIPath = 'path/to/openapi.yml'\nconst tsTypesPath = 'path/to/output/types'\n//\nconst options = {\n  bannerComment: 'Custom banner content'\n}\n\nawait oas2ts(openAPIPath, tsTypesPath, options)\n```\n\n### Generate TypeScript Types from JSON Schemas\n\nTo generate TypeScript types from the generated JSON schemas, provide the path to the JSON schema directory and the output directory for the TypeScript types. Optionally, the third parameter can contain [configuration options](#additional-configuration)\n\n```javascript\nconst schemasPath = 'path/to/output/schemas'\nconst tsTypesPath = 'path/to/output/types'\n\nawait json2ts(schemasPath, tsTypesPath)\n```\n\n### Generate TypeScript exported JSON Schemas from OpenAPI\n\nTo generate TypeScript exported JSON schemas from your OpenAPI specification, provide the path to the OpenAPI file and the output directory for the generated schemas:\n\n```javascript\nconst openAPIPath = 'path/to/openapi.yml'\nconst schemasPath = 'path/to/output/schemas'\nconst propertiesToConvert = 'paths'\n\noas2tson(openAPIPath, schemasPath, propertiesToConvert)\n```\n\n## Example\n\nThe [example](./example) folder contains an example OpenAPI specification and the generated JSON schemas and TypeScript types. To generate the JSON schemas and TypeScript types from the example OpenAPI specification, run:\n\n```sh\n$ npm run oas2json\n```\n\nand then:\n\n```sh\n$ npm run oas2ts\n```\n\nor:\n\n```sh\n$ npm run json2ts\n```\n\n```sh\n$ npm run oas2json\n```\n\nAnd to generate TypeScript exported JSON schema from example OpenAPI specification, run:\n\n```sh\n$ npm run oas2tson\n```\n\nThe generated JSON schemas and TypeScript types will be saved in the output schemas and types folders respectively.\n\n## Additional Configuration\n\nOpenAPI Transformer Toolkit package utilises the [json-schema-to-typescript](https://www.npmjs.com/package/json-schema-to-typescript) package.\n\nThis package allows you to specify [additional options which can be passed to the command when executing](https://www.npmjs.com/package/json-schema-to-typescript#user-content-options), for example to affect the style of output, or change how `additionalProperties` from your API definition is handled.\n\nTo utilise this feature, OpenAPI Transformer Toolkit can read these additional options from a file when being used from a CLI. [An example of this can be found here](https://github.com/nearform/openapi-transformer-toolkit/blob/master/example/json-schema-to-typescript-config.json).\n\nWhen using OpenAPI Transformer Toolkit programmatically, these options can optionally be supplied as the third argument to the `oas2ts` and `json2ts` functions.\n\n[![banner](https://raw.githubusercontent.com/nearform/.github/refs/heads/master/assets/os-banner-green.svg)](https://www.nearform.com/contact/?utm_source=open-source\u0026utm_medium=banner\u0026utm_campaign=os-project-pages)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnearform%2Fopenapi-transformer-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnearform%2Fopenapi-transformer-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnearform%2Fopenapi-transformer-toolkit/lists"}