Skip to content

About

An auto typescript/javascript code generator from swagger.

Topics

Resources

Code of conduct

Stars

86 stars

Watchers

3 watching

Forks

Repository files navigation

NPM

install size dependencies

⭐⭐⭐ If you would like to contribute, please refer to To do list and a list of open tasks.:star::star::star:

Swagger-Typescript: Generate ts/js code from swagger/openApi JSON

Support OpenApi v3, swagger v2 and postman collection

An auto typescript/javascript/kotlin code generator from APIs doc. Each endpoint will be created as a function, full type base. Supported

  • Generating a function for every apis
  • Generating all types, interfaces and enums which used in apis
  • React hooks.
  • SignalR hub.
  • Generating mock data.

For Example: Get method of '/Account' path will be this code in services.ts

import { getAccount } from "./services";

const response = await getAccount({ id: 1234 });

install

$ yarn add swagger-typescript prettier -D && yarn add axios

get start

Before running, add your config to swagger.config.json

swagger.config.json

{
  "url": "http://example.com/api/swagger.json",
  "dir": "./services",
  "prefix": "/api"
}

run

yarn swag-ts

config.ts

more

baseConfig

const baseConfig: AxiosRequestConfig = {
  baseURL: "", // <--- Add your base url
  //other static configs
};

Now you can use APIs, So for advanced config read below.

Use with AI assistants

AI_GUIDE.md explains the config, the generated files and how to call them, written for AI coding assistants (Claude Code, Cursor, Copilot, ChatGPT, ...). It is shipped inside the package, so it always matches your installed version.

Give it to your assistant when you ask for API work:

Read node_modules/swagger-typescript/AI_GUIDE.md, then add a page which lists pets using our generated services.

Or make it permanent by adding this line to your project's AGENTS.md, CLAUDE.md or .cursor/rules:

API calls in this project are generated by swagger-typescript. Before writing or changing API code, read node_modules/swagger-typescript/AI_GUIDE.md

swagger.config.json

For Example:

{
  "$schema": "https://raw.githubusercontent.com/hosseinmd/swagger-typescript/master/schema/v6.json",
  "url": "http://example.com/api/swagger.json",
  "dir": "./services",
  "prettierPath": ".prettierrc",
  "language": "typescript"
}
[Key] [default] Comment
url Required swagger or postman collection Address. can be online or local (json/yaml) (specific branch)
dir Required Address of output
language typescript export to "javascript", "typescript" or "kotlin"
methodName {method}{path} Supported mixed of "{method}{path}{operationId}". for Example: 'service{method}{path}'
prefix Optional prefix value will be removed from method name For example your endpoints is like "/api/v2/users", If you don't want add "/api/v2" to method name, add it to prefix
ignore Optional Ignore headers from type for Example: "ignore": { "headerParams": ["terminalId"]}
mock false For generate response mocks
keepJson false This code will keep previous JSON for updating partially. change it to true then generate service for creating your first json file then you can update a tag for example $ yarn swag-ts User will update your user APIs which have User tag
reactHooks false For generate react hooks of all APIs (using react-query under the hood)
useQuery [] List of apis which is get but developed with post methods (Is useful for rest apis) for Example: ["postTicketsGetall"] (Needed to enable reactHooks)
useInfiniteQuery [] List of apis which is get and could be handle infinity (Needed to enable reactHooks) parameter should be one of page, pageNo or pageNumber
useSuspenseQuery [] List of apis which should use suspense for Example: ["getUsers"] (Needed to enable reactHooks, and react-query v5)
local false update swagger with local swagger.json located in your dir folder. add it to your config file or run it with cli $ yarn swag-ts --local
kotlinPackage Required (Only kotlin) package name of source dir
generateEnumAsType false
includes [] A list of regex patterns that specify which APIs to include based on matching method names
excludes [] A list of regex patterns that specify which APIs to exclude based on matching method names
  • enum ReferralStatus {Successed="Successed","Error"="Error"}
  • type ReferralStatus="Successed" | "Error"; // generateEnumAsType = true

CLI Options

[Key] [default] Comment
local false update swagger with local swagger.json located in your dir folder. add it to your config file or run it with cli $ yarn swag-ts --local
branch Current Branch to generate swagger for develop run yarn swag-ts --branch=develop or your branch name should be develop or a branch which created from develop
config "./swagger.config.json" A path for config file location
- yarn swag-ts --config=./config path is related for "swagger.config.json" file in config folder
- yarn swag-ts --config=./config/myswagger.json you could change config file name
- yarn swag-ts --config=/user/hosseinmd/desktop/config/swagger.config.json you could add absolute path

Config

The config.ts file automatically will be created after first run. You could change this file for customization. Don't change other files, if you want another config create Issue or PR.

  • getAxiosInstance

    getAxiosInstance used for create an instance of axios request you can customize that for what you needed

  • baseConfig

    baseConfig used for get static configs and headers. if you need some dynamic configs like add authentication to headers use requestConfig.headers.authorization into of axiosInstance.interceptors.request.use function.

Extra query key

Query hooks build their react-query key from the endpoint and its params. To add your own values to that key (for example a tenant id, or something you pass through configOverride), use extraQueryKey. The values are appended to the end of the generated key.

// key: [getPets.key, queryParams, "tenant-1"]
const { data } = useGetPets(queryParams, { extraQueryKey: ["tenant-1"] });

// same key outside of a component
const { key } = useGetPets.info(queryParams, undefined, ["tenant-1"]);
await useGetPets.prefetch(queryClient, queryParams, {
  extraQueryKey: ["tenant-1"],
});

Suspense query

To use React Suspense for an api, add its name to useSuspenseQuery. Its hook will be generated with useSuspenseQuery instead of useQuery, so data is always defined, and loading and error are handled by the nearest <Suspense> and error boundary. It needs @tanstack/react-query v5.

{
  "reactHooks": true,
  "useSuspenseQuery": ["getUsers", "getProfile"]
}
// suspends while loading, data is not undefined
const { data } = useGetUsers(queryParams);
  • An api which is not a get will be generated as a query, same as useQuery.
  • An api which is also in useInfiniteQuery will be generated with useSuspenseInfiniteQuery.
  • Suspense hooks do not accept the enabled, placeholderData and throwOnError options.

Run by node

const { generate } = require("swagger-typescript");

generate(config);
// or
generate(); // will be use ./swagger.config.json

Conflict

In some situation teams have parallel backend development which cause conflict when updating swagger for solving this we have partially update, you can update your service just for a few tags and keep other old services codes.

For Doing this you need to add this to your swagger.config.json

"keepJson": true,

This code will keep previous JSON for updating partially.

Run $ yarn swag-ts with your base backend, for example develop branch

Others need to pull this changes

Now you can update Tag1 and Tag2 $ yarn swag-ts Tag1 Tag2.

Multiple Gateway

if you have multiple gateway in your project you could handle it by add array of config in swagger.config.json

[
  {
    "$schema": "https://raw.githubusercontent.com/hosseinmd/swagger-typescript/master/schema/v6.json",
    "url": "http://example1.com/api/swagger.json",
    "dir": "./service1",
    "prettierPath": ".prettierrc",
    "language": "typescript"
  },
  {
    "$schema": "https://raw.githubusercontent.com/hosseinmd/swagger-typescript/master/schema/v6.json",
    "url": "http://example2.com/api/swagger.json",
    "dir": "./service2",
    "prettierPath": ".prettierrc",
    "language": "typescript"
  }
]

Specific branch

if you are managing project by multiple branch like gitflow, you need to update swagger based on you working branch or parent branch (for example your parent is develop if you create a branch from develop).

For Example:

{
  "url": [
    {
      "branch": "master",
      "url": "http:/example.com/api/swagger.json"
    },
    {
      "branch": "develop",
      "url": "http://stage.example.com/api/swagger.json"
    }
  ]
}

to generate swagger for develop run yarn swag-ts --branch=develop or your branch name should be develop or a branch which created from develop

Stories

why-you-should-use-swagger-typescript-for-generate-apis-code

About

An auto typescript/javascript code generator from swagger.

Topics

Resources

Code of conduct

Stars

86 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages