{"id":19972628,"url":"https://github.com/jpb06/swagger-typescript-types","last_synced_at":"2025-05-04T01:30:52.445Z","repository":{"id":41516834,"uuid":"405394641","full_name":"jpb06/swagger-typescript-types","owner":"jpb06","description":"Generating typescript typings from swagger","archived":false,"fork":false,"pushed_at":"2024-04-25T14:39:52.000Z","size":706,"stargazers_count":4,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-21T23:39:00.580Z","etag":null,"topics":["api-rest","nodejs","openapi","swagger","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/jpb06.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}},"created_at":"2021-09-11T14:04:00.000Z","updated_at":"2025-03-04T15:32:48.000Z","dependencies_parsed_at":"2024-11-13T06:01:05.369Z","dependency_job_id":null,"html_url":"https://github.com/jpb06/swagger-typescript-types","commit_stats":{"total_commits":146,"total_committers":3,"mean_commits":"48.666666666666664","dds":0.2191780821917808,"last_synced_commit":"b8645752caa119aa9e3d6e2a920e32646d49f33e"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpb06%2Fswagger-typescript-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpb06%2Fswagger-typescript-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpb06%2Fswagger-typescript-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpb06%2Fswagger-typescript-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpb06","download_url":"https://codeload.github.com/jpb06/swagger-typescript-types/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252276955,"owners_count":21722447,"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":["api-rest","nodejs","openapi","swagger","typescript"],"created_at":"2024-11-13T03:08:44.624Z","updated_at":"2025-05-04T01:30:51.826Z","avatar_url":"https://github.com/jpb06.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger-typescript-types\n\n[![Open in Visual Studio Code](https://img.shields.io/static/v1?logo=visualstudiocode\u0026label=\u0026message=Open%20in%20Visual%20Studio%20Code\u0026labelColor=2c2c32\u0026color=007acc\u0026logoColor=007acc)](https://github.dev/jpb06/swagger-typescript-types)\n![npm bundle size](https://img.shields.io/bundlephobia/min/swagger-typescript-types)\n![Github workflow](https://img.shields.io/github/actions/workflow/status/jpb06/swagger-typescript-types/tests-scan.yml?branch=master\u0026logo=github-actions\u0026label=last%20workflow)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=jpb06_swagger-typescript-types)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=jpb06_swagger-typescript-types)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=jpb06_swagger-typescript-types)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=jpb06_swagger-typescript-types)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=jpb06_swagger-typescript-types)\n![Coverage](./badges/coverage-jest%20coverage.svg)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=ncloc)](https://sonarcloud.io/summary/new_code?id=jpb06_swagger-typescript-types)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=jpb06_swagger-typescript-types)\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=code_smells)](https://sonarcloud.io/dashboard?id=jpb06_swagger-typescript-types)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=jpb06_swagger-typescript-types)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=jpb06_swagger-typescript-types)\n![Snyk Vulnerabilities for npm package](https://img.shields.io/snyk/vulnerabilities/npm/swagger-typescript-types?label=snyk%20vulnerabilities)\n[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=jpb06_swagger-typescript-types\u0026metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=jpb06_swagger-typescript-types)\n![Last commit](https://img.shields.io/github/last-commit/jpb06/swagger-typescript-types?logo=git)\n\nGenerating typescript types from swagger.\n\n\u003c!-- readme-package-icons start --\u003e\n\n\u003cp align=\"left\"\u003e\u003ca href=\"https://docs.github.com/en/actions\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/GithubActions-Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://www.typescriptlang.org/docs/\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/TypeScript.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://nodejs.org/en/docs/\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/NodeJS-Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://pnpm.io/motivation\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/Pnpm-Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://axios-http.com/fr/docs/intro\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/Axios-Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://github.com/conventional-changelog\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/CommitLint.Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://eslint.org/docs/latest/\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/Eslint-Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://jestjs.io/docs/getting-started\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/Jest.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://prettier.io/docs/en/index.html\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/Prettier-Dark.svg\" /\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://swc.rs/docs/getting-started\" target=\"_blank\"\u003e\u003cimg height=\"50\" src=\"https://raw.githubusercontent.com/jpb06/jpb06/master/icons/Swc-Dark.svg\" /\u003e\u003c/a\u003e\u003c/p\u003e\n\n\u003c!-- readme-package-icons end --\u003e\n\n## ⚡ Purpose\n\nHere is a little utility to generate typescript artifacts from swagger. This can be useful when you want to sync types between your backend and your frontend.\n\nFor example, we have [this backend](https://devfriends-backend.fly.dev) exposing a swagger. The `/devs/by-squads` route returns an array of `DevDto` which is a model described in swagger.\n\nNow, I could just write the interface for it myself in the frontend codebase 🤔, right? This is simple enough in our example:\n\n```typescript\nexport interface DevDto {\n  id: number;\n  idSquad: number;\n  firstName: string;\n  avatar: string;\n}\n```\n\nBut what if we could just extract these models and generate types instead? Oh...! 😏\n\n### 🔶 Disclaimer\n\n🚨 I wrote this for a stack based on [nestjs](https://nestjs.com/) for the backend and [react-query](https://react-query.tanstack.com/) for the frontend, so this tool may or may not suit your needs. If you think about another usecase, do not hesitate to drop an issue 🙃.\n\n## ⚡ Installation\n\nTo install, use either yarn or npm:\n\n```bash\nyarn add -D swagger-typescript-types\n```\n\n```bash\nnpm i -D swagger-typescript-types\n```\n\n## ⚡ Typical use : cli\n\n### 🔶 From an url\n\nLet's say we have a backend exposing endpoints on this url: \u003chttps://devfriends-backend.fly.dev\u003e.\nNow, swagger exposes a json file on the [/-json](https://devfriends-backend.fly.dev/-json) path in this example.\n\nKnowing this, we can add a script to our package.json:\n\n```json\n{\n  \"scripts\": {\n    \"api:sync\": \"generateTypesFromUrl -u https://devfriends-backend.fly.dev/-json -o ./src/api/types [-t]\"\n  }\n}\n```\n\nThe `generateTypesFromUrl` task takes two arguments:\n\n| name | description                                         | Example                                               |\n| ---- | --------------------------------------------------- | ----------------------------------------------------- |\n| u    | The url of the json exposed by the targeted swagger | \u003chttps://devfriends-backend.fly.dev/-json\u003e |\n| o    | Where to write our exposed types                    | ./src/api/types                                       |\n\nOptionally, you can use `-t` flag if you're using `importsNotUsedAsValues` in your tsconfig compiler options. It will generate imports like so:\n\n```typescript\nimport type { ... } from ...\n```\n\nOur task will do a few things using these arguments when called:\n\n```misc\n✔️ Fetch the json exposed by our swagger (exposed in our example at the `-json` path).\n✔️ Validate the json retrieved against [openapiv3 schema](https://github.com/APIDevTools/openapi-schemas).\n✔️ Extract models and generate typings from them.\n✔️ Write them on the path defined as second argument (./src/api/types/api-types.ts).\n✔️ For each route, create a file containing the endpoint path and re-exporting parameters / request body / responses types.\n✔️ Warn us if some specs are missing (missing response types, missing path parameters, etc.).\n```\n\n### 🔶 From a file\n\nWe can also generate types from a file:\n\n```json\n{\n  \"scripts\": {\n    \"api:sync\": \"generateTypesFromFile -i ./specs/swagger.json -o ./src/api/types [-t]\"\n  }\n}\n```\n\nThe `generateTypesFromUrl` task takes two arguments:\n\n| name | description                       | Example              |\n| ---- | --------------------------------- | -------------------- |\n| i    | The path of the swagger json file | ./specs/swagger.json |\n| o    | Where to write our exposed types  | ./src/api/types      |\n\nOptionally, you can use `-t` flag if you're using `importsNotUsedAsValues` in your tsconfig compiler options. It will generate imports like so:\n\n```typescript\nimport type { ... } from ...\n```\n\nAgain, our task will do the following:\n\n```misc\n✔️ Read the json file.\n✔️ Validate it against [openapiv3 schema](https://github.com/APIDevTools/openapi-schemas).\n✔️ Extract models and generate typings from it.\n✔️ Write them on the path defined as second argument (./api-types.ts).\n✔️ For each route, create a file containing the endpoint path and re-exporting parameters / request body / responses types.\n✔️ Warn us if some specs are missing (missing response types, missing path parameters, etc.).\n```\n\n## ⚡ Generated files\n\nTaking our example backend, let's check the files generated:\n\n\u003e ./api-types.ts\n\n```Typescript\nexport interface SquadDto {\n  id: number;\n  name: string;\n}\nexport interface AllSquadsResultDto {\n  result: Array\u003cSquadDto\u003e;\n}\nexport interface ApiResponseDto {\n  statusCode: number;\n  message: string;\n}\nexport interface DevDto {\n  id: number;\n  idSquad: number;\n  firstName: string;\n  avatar: string;\n}\nexport interface SquadsDevelopersResultDto {\n  result: Array\u003cDevDto\u003e;\n}\nexport interface BadRequestDto {\n  statusCode: number;\n  message: string | Array\u003cstring\u003e;\n  error: string;\n}\nexport interface AllDevsResultDto {\n  result: Array\u003cDevDto\u003e;\n}\nexport interface ChangeSquadBodyDto {\n  idDev: number;\n  idSquad: number;\n}\nexport interface ChangeSquadResultDto {\n  result: string;\n}\nexport interface DevelopersBySquadsBodyDto {\n  idSquads: Array\u003cnumber\u003e;\n}\nexport interface DevelopersBySquadsResultDto {\n  result: Array\u003cDevDto\u003e;\n}\n```\n\nNow let's check an [endpoint](https://devfriends-backend.fly.dev/#/squads/SquadsController_getSquadsDevelopers):\n\n\u003e ./SquadsController/getSquadsDevelopers.ts\n\n```Typescript\n/*\n * method: get\n * summary: Get the developers belonging to a squad\n * description: Retrieves the squad developers\n */\n\nimport { SquadsDevelopersResultDto, BadRequestDto, ApiResponseDto } from './../api-types';\n\nexport const getPath = (id: number): string =\u003e `/squads/${id}/devs`;\n\nexport type GetSquadsDevelopersSuccess = SquadsDevelopersResultDto;\nexport type GetSquadsDevelopersError = BadRequestDto | ApiResponseDto;\n```\n\n## ⚡ Api\n\nOn top of the cli, this package exposes the following functions:\n\n### 🔶 Functions\n\n#### 🌀 generateTypesFromUrl\n\nThis function generates types from a swagger exposed online. Typical use:\n\n```typescript\nconst params = {\n  swaggerJsonUrl: 'https://devfriends-backend.fly.dev/-json',\n  outputPath './src/specs',\n  importsNotUsedAsValues: false\n};\n\nconst {\n  typesGenerated, // boolean, specifies whether types have been extracted (./api-types.ts file)\n  endpointsCount  // number of endpoints extracted\n}: GenerationResult = await generateTypesFromUrl(params);\n```\n\n#### 🌀 generateTypesFromFile\n\nThis function generates types from a swagger json file. Typical use:\n\n```typescript\nconst params = {\n  inputPath: './src/api/swagger.json',\n  outputPath './src/specs',\n  importsNotUsedAsValues: false\n};\n\nconst {\n  typesGenerated, // boolean, specifies whether types have been extracted (./api-types.ts file)\n  endpointsCount  // number of endpoints extracted\n}: GenerationResult = await generateTypesFromFile(params);\n```\n\n#### 🌀 validateSchema\n\nThis function validates some arbitrary json against the [openapiv3 schema](https://github.com/APIDevTools/openapi-schemas). Typically use:\n\n```typescript\nconst json: InputSwaggerJson = { ... };\n\nconst schema: ValidatedOpenaApiSchema = await validateSchema(data);\n```\n\n#### 🌀 generateTypesDefinitions\n\nThis function extracts models from the swagger json and generates typings from them. Typical use:\n\n```typescript\nconst outPath = './src/api/types';\nconst schema: ValidatedOpenaApiSchema = { ... };\nconst importsNotUsedAsValues = true\n\nawait generateTypesDefinitions(outPath, schema, importsNotUsedAsValues);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpb06%2Fswagger-typescript-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpb06%2Fswagger-typescript-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpb06%2Fswagger-typescript-types/lists"}