[//]: # ( )
[//]: # (This file is automatically generated by a metapak)
[//]: # (module. Do not change it except between the)
[//]: # (content:start/end flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )

schema2dts

> A very simple JSONSchema7/OpenAPI3 to TypeScript types definitions generator

[//]: # (::contents:start)

It is intended to support JSONSchema7/OpenAPI3 but may work for some if not most
JSONSchema versions.

This module assumes your JSONSchema / OpenAPI3 documents are valid. It also
doesn't support external references at the moment (and probably for ever) and
expect a single object whose definitions are all relative to the root object.

It is also meant to be a building block for higher level generators.

Usage

``ts
import { readFile, writeFile } from 'node:fs/promises';
import {
generateJSONSchemaTypes,
generateOpenAPITypes,
toSource,
} from 'schema2dts';

// Open API
const openAPISchema = JSON.parse(readFileSync('openapi.json').toString());

await writeFile(
'API.d.ts',
toSource(await generateOpenAPITypes(openAPISchema)),
);

// JSON Schema
const jsonSchema = JSON.parse(readFileSync('schema.json').toString());

await writeFile(
'API.d.ts',
toSource(await generateJSONSchemaTypes(jsonSchema)),
);
`

If you find some cases with unexpected results, please add the fixtures to this
repository in a pull request and describe the problem you encounter.

Options

You can change the API main namespace in order to be able to use several
generated types in the same repository. Just provide its namespace a the second
argument to generateOpenAPITypes.

The third argument is for options:

- you can generate the unused schemas (especially useful when in development
mode) to be able to use them in your code despite the fact they ain't used in
you API at that moment. Just set generateUnusedSchemas to true.
- you can also filter the statuses you wish to generate by setting
filterStatuses to [200, 201, 202, 300] for example so that the 500 errors
responses ain't taken in count.

Known issues

There is some differences between the JSONSchema anyOf, allOf and oneOf
keywords (learn
more here on combining schemas).

The current way to handle this in this library is to:

- convert oneOf to an
union type
which is valid
- convert anyOf to an union type too which is not really what it means in JSON
Schema
- convert allOf to an
intersection type
which is completly wrong and will work only with JSON Schemas meant to be used
that way. By example, combining an existing object schema with another object
to make some properties required will only work if you set its type to
object in both schemas explicitly:

`json
{
"allOf": [
{
"$ref": "#/definitions/User"
},
{ "type": "object", "required": ["id"] }
]
}
`

Currently, the if/then keywords of JSONSchema do not work. You should be
able to replace most of its use per a oneOf` form.

[//]: # (::contents:end)

API

Functions

generateOpenAPITypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from an Open API document

generateJSONSchemaTypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from a JSONSchema document

toSource(nodes) ⇒

Returns source from a list of TypeScript statements

generateOpenAPITypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from an Open API document

Kind: global function

| Param | Type | Description |
| --- | --- | --- |
| schema | JSONSchema.Document | |
| options | Object | |
| options.baseName | string | |
| options.filterStatuses | Array.<number> | |
| options.generateUnusedSchemas | boolean | |
| options.camelizeInputs | boolean | |
| options.brandedTypes | Array.<string> | Brand types by names |
| options.brandedFormats | Array.<string> | Brand formats by names |
| options.typedFormats | Object | Substitute string format by a type |
| options.generateRealEnums | boolean | |
| options.tuplesFromFixedArraysLengthLimit | number | |
| options.exportNamespaces | boolean | |
| options.requireCleanAPI | boolean | |

generateJSONSchemaTypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from a JSONSchema document

Kind: global function

| Param | Type | Description |
| --- | --- | --- |
| schema | JSONSchema.Document | |
| options | Object | |
| options.baseName | string | |
| options.brandedTypes | Array.<string> | Brand types by names |
| options.brandedFormats | Array.<string> | Brand formats by names |
| options.typedFormats | Object | Substitute string format by a type |
| options.generateRealEnums | boolean | |
| options.tuplesFromFixedArraysLengthLimit | number | |
| options.exportNamespaces | boolean | |

toSource(nodes) ⇒

Returns source from a list of TypeScript statements

Kind: global function
Returns: string

| Param | Type |
| --- | --- |
| nodes | TypedPropertyDescriptor.NodeArray |

Authors

- Nicolas Froidure

License

ISC