# openapi-typescript-validator-ext-ref

> Generate typescript with ajv validation based on openapi schemas

Latest version **3.2.0-external-ref-support** (published 2022-04-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install openapi-typescript-validator-ext-ref
pnpm add openapi-typescript-validator-ext-ref
yarn add openapi-typescript-validator-ext-ref
bun add openapi-typescript-validator-ext-ref
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.0-external-ref-support |
| Published | 2022-04-09 |
| First published | 2022-04-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 71.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Q42 |
| Maintainers | kisfejes |
| Keywords | openapi, schema, json schema, typescript, generator, generate, validator, validate, json |

## Links

- npm: https://www.npmjs.com/package/openapi-typescript-validator-ext-ref
- Repository: github.com/Kisfejes/openapi-typescript-validator
- Homepage: https://github.com/Kisfejes/openapi-typescript-validator
- npm.io page: https://npm.io/package/openapi-typescript-validator-ext-ref

## Dependencies (7)

- [ajv](https://npm.io/package/ajv.md) ^8.1.0
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.0.0
- [ajv-formats](https://npm.io/package/ajv-formats.md) ^2.0.2
- [lodash.keyby](https://npm.io/package/lodash.keyby.md) ^4.6.0
- [json-schema-to-typescript](https://npm.io/package/json-schema-to-typescript.md) ^10.1.3
- [@apidevtools/json-schema-ref-parser](https://npm.io/package/@apidevtools/json-schema-ref-parser.md) ^9.0.9
- [@openapi-contrib/openapi-schema-to-json-schema](https://npm.io/package/@openapi-contrib/openapi-schema-to-json-schema.md) ^3.0.4

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.2.0-external-ref-support (latest) — 2022-04-09

## README

# openapi-typescript-validator
Generate typescript with `ajv >= 8.0.0` validation based on openapi schemas

- [What does this do?](#what-does-this-do)
- [Getting started](#getting-started)
- [Documentation](#documentation)
  - [generate](#generate)

## 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)
```yaml
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required: ['id']
```

Will convert to:

```typescript
export interface User {
  id: string;
  name?: string;
}
```

And will generate a decoder:

```typescript
// 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:

```typescript
const user = UserDecoder.decode({
  id: 1
});

// User: /id: should be string. JSON: {"id":1}
```

### References
References als work, this schema

```json
{
  "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

```typescript
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`
```javascript
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](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](https://github.com/ajv-validator/ajv) for the decoders
```
npm i ajv
```

Your `tsconfig.json` file will need to be able to resolve the json files.
```json
"resolveJsonModule": true
```

Create a node script called `generate-schemas.js`
```javascript

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` with `ajv` depedency and `ajv-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
```javascript
// v2
object({ title: string })

// v3:
object({ title: string() })
```

## Documentation

### generate
`generate` can be called with [GenerateOptions](src/GenerateOptions.ts). See the file for more info.

---
_Source: https://npm.io/package/openapi-typescript-validator-ext-ref · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
