openapi-typescript-validator
v4.0.0
Published
Generate typescript with ajv validation based on openapi schemas
Downloads
2,654
Readme
openapi-typescript-validator
Generate typescript with ajv >= 8.0.0
validation based on openapi schemas
What does this do?
This package will convert your openapi 3.0
spec to:
- Typescript models
- Decoders which validate your models against a JSON schema
Example
This schema (note: also works with JSON based schema's)
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
required: ['id']
Will convert to:
export interface User {
id: string;
name?: string;
}
And will generate a decoder:
// user will be of type User if the JSON is valid
const user = UserDecoder.decode(json);
If the JSON is invalid, it will throw an error:
const user = UserDecoder.decode({
id: 1
});
// User: /id: should be string. JSON: {"id":1}
References
References als work, this schema
{
"components": {
"schemas": {
"Screen": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": { "$ref": "#/components/schemas/Component" }
}
},
"required": [ "components" ]
},
"Component": {
"anyOf": [
{ "$ref": "#/components/schemas/TitleComponent" },
{ "$ref": "#/components/schemas/ImageComponent" }
]
},
"TitleComponent": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["title"]
},
"title": {
"type": "string"
},
"subtitle": {
"type": "string",
"nullable": true
}
},
"required": [ "type", "title" ]
},
"ImageComponent": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["image"]
},
"url": {
"type": "string"
}
},
"required": [ "type", "url" ]
}
}
}
}
will generate
export type Component = TitleComponent | ImageComponent;
export interface Screen {
components: Component[];
}
export interface TitleComponent {
type: "title";
title: string;
subtitle?: string | null;
}
export interface ImageComponent {
type: "image";
url: string;
}
Custom builder
We also created a way to define your JSON schema a bit easier. The example above can also be written as:
Example: custom-schema.js
const { anyOf, array, constant, nillable, object, string } = require('openapi-typescript-validator');
const types = {};
types.Screen = object({
components: array('Component'),
})
types.Component = anyOf(['TitleComponent', 'ImageComponent']);
types.TitleComponent = object({
type: constant('title'),
title: string(),
subtitle: nillable(string),
});
types.ImageComponent = object({
type: constant('image'),
url: string(),
});
module.exports = { types }
Just call generate
with schemaType: custom
.
See src/builder.ts for all helpers which can be used.
Getting started
Install the package
npm i openapi-typescript-validator --save-dev
We use ajv for the decoders
npm i ajv
Your tsconfig.json
file will need to be able to resolve the json files.
"resolveJsonModule": true
Create a node script called generate-schemas.js
const path = require('path');
const { generate } = require('openapi-typescript-validator');
generate({
schemaFile: path.join(__dirname, 'myswagger.yaml'),
schemaType: 'yaml',
directory: path.join(__dirname, '/generated')
})
and run node generate-schemas.js
Note We recommened to setup your schema configuration in a different folder than your application. E.g:
schemas
package.json
which depends on this library
server
package.json
withajv
depedency andajv-formats
(if you use formats)
Breaking changes
upgrading to V3
When using the custom
format for your schemas. The string
, boolean
, number
, etc helpers are now a function
instead of const
.
You'll need to update your schemas
// v2
object({ title: string })
// v3:
object({ title: string() })
Documentation
generate
generate
can be called with GenerateOptions. See the file for more info.