@gr2m/openapi-typescript
v4.0.0-fork.2
Published
Generate TypeScript types from Swagger OpenAPI specs
Downloads
11
Maintainers
Readme
📘️ openapi-typescript
🚀 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
--auth
flag) - ✅ Supports remote references:
$ref: "external.yaml#components/schemas/User"
- ✅ Formats using Prettier
- ✅ TypeScript 4.0 features
Examples
Usage
🖥️ CLI
🗄️ Reading specs from file system
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!
☁️ Reading specs from remote resource
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!
Using in TypeScript
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!
Outputting to stdout
Simply omit the --output
flag to return to stdout:
npx openapi-typescript schema.yaml
CLI Options
| 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) |
| --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 |
| --raw-schema
| | false
| Generate TS types from partial schema (e.g. having components.schema
at the top level) |
🐢 Node
npm i --save-dev openapi-typescript
const fs = require("fs");
const openapiTS = require("openapi-typescript").default;
// 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 = path.join(__dirname, 'spec.yaml'); // 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.
⚠️ As of v4.0
, openapiTS()
is an async function.
Custom Formatter
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-time
By 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.
🏅 Project Goals
- 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
PascalCase
or 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.
🤝 Contributing
PRs are welcome! Please see our CONTRIBUTING.md guide. Opening an issue beforehand to discuss is encouraged but not required.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!