Skip to content

A very simple JSONSchema to TypeScript types generator

License

Notifications You must be signed in to change notification settings

nfroidure/schema2dts

Repository files navigation

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

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

License

ISC

About

A very simple JSONSchema to TypeScript types generator

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Sponsor this project

 

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •