schema2dts

A very simple JSONSchema7/OpenAPI3 to TypeScript types definitions generator

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 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

import { readFileSync, writeFileSync } from 'fs';
import {
  generateJSONSchemaTypes,
  generateOpenAPITypes,
  toSource,
} from 'schema2dts';

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

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

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

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

If you find some case 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:

{
  "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.

API

Functions

generateOpenAPITypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from an Open API document

Kind: global function

| Param | Type | | --- | --- | | schema | JSONSchema.Document | | options | Object | | options.baseName | string | | options.filterStatuses | Array.<number> | | options.generateUnusedSchemas | boolean | | options.camelizeInputs | boolean | | options.brandedTypes | Array.<string> | | options.generateRealEnums | boolean | | 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 | | --- | --- | | schema | JSONSchema.Document | | options | Object | | options.name | string | | options.brandedTypes | Array.<string> |

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