Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nfroidure/schema2dts

A very simple JSONSchema to TypeScript types generator
https://github.com/nfroidure/schema2dts

hacktoberfest jsonschema openapi3

Last synced: 3 months ago
JSON representation

A very simple JSONSchema to TypeScript types generator

Awesome Lists containing this project

README 

        
[//]: # ( )

[//]: # (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 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 { 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](https://json-schema.org/understanding-json-schema/reference/combining.html)).



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



- convert `oneOf` to an

  [union type](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#union-types)

  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](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#intersection-types)

  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 |

| --- | --- |

| 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](https://insertafter.com/en/index.html)



# License

[ISC](https://github.com/nfroidure/schema2dts/blob/main/LICENSE)