π Convert OpenAPI 3.0 and 2.0 (Swagger) schemas to TypeScript interfaces using Node.js.
Features
- β OpenAPI 3.0
- β Swagger 2.0
- β Supports YAML and JSON schema formats
- β
Supports loading via remote URL (simple authentication supported with the
--authflag) - β
Supports remote references:
$ref: "external.yaml#components/schemas/User" - β Formats using Prettier
- β TypeScript 4.0 features
Examples
npx openapi-typescript schema.yaml --output schema.ts
# π Loading spec from schema.yamlβ¦
# π schema.yaml -> schema.ts [250ms]
npx openapi-typescript "specs/**/*.yaml" --output schemas/
# π Loading spec from specs/one.yamlβ¦
# π Loading spec from specs/two.yamlβ¦
# π Loading spec from specs/three.yamlβ¦
# π specs/one.yaml -> schemas/specs/one.ts [250ms]
# π specs/two.yaml -> schemas/specs/two.ts [250ms]
# π specs/three.yaml -> schemas/specs/three.ts [250ms]Note: if generating a single schema, --output must be a file (preferably *.ts). If using globs, --output must be a directory.
Thanks to @sharmarajdaksh for the glob feature!
npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts
# π Loading spec from https://petstore.swagger.io/v2/swagger.jsonβ¦
# π https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]Note: globbing doesnβt work for remote schemas because there is no reliable way to determine a list of files to select from a remote file system.
Thanks to @psmyrdek for the remote spec feature!
Import any top-level item from the generated spec to use it. It works best if you also alias types to save on typing:
import { components } from "./generated-schema.ts";
type APIResponse = components["schemas"]["APIResponse"];Because OpenAPI schemas may have invalid TypeScript characters as names, the square brackets are a safe way to access every property.
Also note that thereβs a special operations interface that you can import OperationObjects by their operationId:
import { operations } from "./generated-schema.ts";
type getUsersById = operations["getUsersById"];Even though operations isnβt present in your original schema, itβs a simple convenience and wonβt disrupt any of your other types.
Thanks to @gr2m for the operations feature!
The generated spec can also be used with openapi-typescript-fetch which implements a typed fetch client for openapi-typescript.
import { paths } from "./petstore";
import { Fetcher } from "openapi-typescript-fetch";
// declare fetcher for paths
const fetcher = Fetcher.for<paths>()
// global configuration
fetcher.configure({
baseUrl: "https://petstore.swagger.io/v2",
init: {
headers: {
...
},
},
use: [...] // middlewares
})
// create fetch operations
const findPetsByStatus = fetcher.path("/pet/findByStatus").method("get").create()
const addPet = fetcher.path("/pet").method("post").create()
// fetch
try {
const { status, data: pets } = await findPetsByStatus({
status: ["available", "pending"],
})
await addPet({ ... })
} catch(e) {
// check which operation threw the exception
if (e instanceof addPet.Error) {
// get discriminated union { status, data }
const error = e.getActualType()
if (error.status === 400) {
error.data.validationErrors // 400 response data
} else if (error.status === 500) {
error.data.errorMessage // 500 response data
} else {
...
}
}
}Simply omit the --output flag to return to stdout:
npx openapi-typescript schema.yaml| Option | Alias | Default | Description |
|---|---|---|---|
--output [location] |
-o |
(stdout) | Where should the output file be saved? |
--auth [token] |
(optional) Provide an auth token to be passed along in the request (only if accessing a private schema) | ||
--header |
-x |
(optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern |
|
--headersObject |
-h |
(optional) Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over --header |
|
--httpMethod |
-m |
GET |
(optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL |
--immutable-types |
-it |
false |
(optional) Generates immutable types (readonly properties and readonly array) |
--additional-properties |
-ap |
false |
(optional) Allow arbitrary properties for all schema objects without additionalProperties: false |
--default-non-nullable |
false |
(optional) Treat schema objects with default values as non-nullable | |
--prettier-config [location] |
-c |
(optional) Path to your custom Prettier configuration for output | |
--export-type |
false |
(optional) Export type instead of interface |
|
--support-array-length |
false |
(optional) Generate tuples using array minItems / maxItems | |
--make-paths-enum |
-pe |
false |
(optional) Generate an enum of endpoint paths |
--path-params-as-types |
false |
(optional) Substitute path parameter names with their respective types | |
--raw-schema |
false |
Generate TS types from partial schema (e.g. having components.schema at the top level) |
|
--version |
Force OpenAPI version with --version 3 or --version 2 (required for --raw-schema when version is unknown) |
npm i --save-dev openapi-typescriptimport fs from "fs";
import openapiTS from "openapi-typescript";
// example 1: load [object] as schema (JSON only)
const schema = await fs.promises.readFile("spec.json", "utf8") // must be OpenAPI JSON
const output = await openapiTS(JSON.parse(schema));
// example 2: load [string] as local file (YAML or JSON; released in v4.0)
const localPath = new URL("./spec.yaml", import.meta.url); // may be YAML or JSON format
const output = await openapiTS(localPath);
// example 3: load [string] as remote URL (YAML or JSON; released in v4.0)
const output = await openapiTS("https://myurl.com/v1/openapi.yaml");The Node API may be useful if dealing with dynamically-created schemas, or youβre using within context of a larger application. Pass in either a JSON-friendly object to load a schema from memory, or a string to load a schema from a local file or remote URL (it will load the file quickly using built-in Node methods). Note that a YAML string isnβt supported in the Node.js API; either use the CLI or convert to JSON using js-yaml first.
v4.0, openapiTS() is an async function.
If using the Node.js API, you can optionally pass a formatter to openapi-typescript. This is useful if you want to override the default types and substitute your own.
For example, say your schema has the following property:
properties:
updated_at:
type: string
format: date-timeBy default, this will generate a type updated_at?: string;. But we can override this by passing a formatter to the Node API, like so:
const types = openapiTS(mySchema, {
formatter(node: SchemaObject) {
if (node.format === "date-time") {
return "Date"; // return the TypeScript βDateβ type, as a string
}
// for all other schema objects, let openapi-typescript decide (return undefined)
});This will generate updated_at?: Date instead. Note that you will still have to do the parsing of your data yourself. But this will save you from having to also update all your types.
Note: you donβt have to use .formatβthis is just an example! You can use any property on a schema object to overwrite its generated type if desired.
- Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
- The generated TypeScript types must match your schema as closely as possible (i.e. donβt convert names to
PascalCaseor follow any TypeScript-isms; faithfully reproduce your schema as closely as possible, capitalization and all) - This library is a TypeScript generator, not a schema validator.
PRs are welcome! Please see our CONTRIBUTING.md guide. Opening an issue beforehand to discuss is encouraged but not required.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!