Ts-openapi-dsl NPM

TypeScript OpenAPI DSL

Build OpenAPI3 contracts declaratively.

Install

npm i ts-openapi-dsl

Usage

Example

spec.paths = paths({
  getUser: operation({
    method: 'get',
    path: '/users/:id',
    responses: {
      200: json({
        schema: array(string()),
      }),
    },
  }),
});

// same as
spec.paths = {
  '/users/:id': {
    'get': {
      operationId: 'getUser',
      responses: {
        '200': {
          content: {
            'application/json': {
              schema: {
                type: 'array',
                items: {
                  type: 'string',
                },
              },
            },
          },
        },
      },
    },
  },
};

Schema helpers

Schema helpers can be used to remove some boilerplate around JSON schema definitions. Every helper returns a JSON schema object.

import { types as t } from 'ts-openapi-dsl';

const User = t.object('An object that represents a user', {
  id: t.integer('The ID of the user'),
  name: t.string('The name of the user'),
  createdAt: t.dateTime(),
  foo: {
    type: 'string',
    description: 'You can use raw JSON schema as well...',
  },
});

Every helper accepts an extra parameter that can be used to decorate the schema with additional properties.

`boolean(description?: string, extra?: Schema): Schema`

Defines a boolean schema, essentially:

const type = {
  type: 'boolean',
  description,
  ...extra,
};

`integer(description?: string, extra?: Schema): Schema`

Defines an integer schema, essentially:

const type = {
  type: 'integer',
  description,
  ...extra,
};

`number(description?: string, extra?: Schema): Schema`

Defines an number schema, essentially:

const type = {
  type: 'number',
  description,
  ...extra,
};

`string(description?: string, extra?: Schema): Schema`

Defines a string schema, essentially:

const type = {
  type: 'string',
  description,
  ...extra,
};

`pattern(pattern: RegExp, description?: string, extra?: Schema): Schema`

Defines a string schema with a regex pattern.

`date(description?: string, extra?: Schema): Schema`

Defines a string schema with date format.

`dateTime(description?: string, extra?: Schema): Schema`

Defines a string schema with date-time format.

`binary(description?: string, extra?: Schema): Schema`

Defines a string schema with binary format.

`email(description?: string, extra?: Schema): Schema`

Defines a string schema with email format.

`constant(value: string, description?: string, extra?: Schema): Schema`

Defines a string schema with an enum that only accept a single value, essentially:

const type = {
  type: 'string',
  description,
  enum: [value],
  ...extra,
};

`choice(values: Record<string, string>, extra?: Schema): Schema`

Defines a string schema with an enum that only accepts predefined values. Keys of values are the allowed values, and the corresponding values in the object are the descriptions.

const type = choice({
  FOO: 'Description of FOO',
  BAR: 'Description of BAR',
});

// same as
cons type = {
  type: 'string',
  enum: ['FOO', 'BAR'],
  description: '* `FOO` - Description of FOO\n* `BAR` - Description of BAR',
};

`array(items: Schema, description?: string, extra?: Schema): Schema`

Defines an array schema with the specified items, essentially:

const type = {
  type: 'array',
  description,
  items,
  ...extra,
};

`object(properties: Record<string, Schema>, description?: string, extra?: Schema): Schema`

Defines an object schema with the specified properties.

Every helpers has an optional variant, eg. string.optional(...), which signals to its parent object to make it an optional property.

Objects are strict by default (ie. additionalProperties is set to false).

const type = object({
  foo: string(),
  bar: string.optional(),
});

// same as
const type = {
  type: 'object',
  additionalProperties: false,
  required: ['foo'],
  properties: {
    foo: {
      type: 'string',
    },
    bar: {
      type: 'string',
    },
  },
};

`required(schema: Schema): Schema`

Turns the given schema into a required schema (ie. in a wrapper object, it'll be a required property).

const wrapped = string.optional();

const wrapper = object({
  foo: wrapped,
  bar: required(wrapped),
});

// same as
const wrapper = {
  type: 'object',
  additionalProperties: false,
  required: ['bar'],
  properties: {
    foo: { type: 'string' },
    bar: { type: 'string' },
  },
};

`optional(schema: Schema): Schema`

Turns the given schema into an optional schema (ie. in a wrapper object, it won't be a required property).

const wrapped = string.required();

const wrapper = object({
  foo: wrapped,
  bar: optional(wrapped),
});

// same as
const wrapper = {
  type: 'object',
  additionalProperties: false,
  required: ['foo'],
  properties: {
    foo: { type: 'string' },
    bar: { type: 'string' },
  },
};

OpenAPI helpers

`response(props: Response): ResponseObject`

Defines a response object with a single media type:

const res = response({
  description: 'Response description',
  headers,
  links,
  type: 'application/json',
  schema,
  examples,
  encoding,
});

// same as
const res = {
  description: 'Response description',
  headers,
  links,
  content: {
    'application/json': {
      schema,
      examples,
      encoding,
    },
  },
};

`json(props: Response): ResponseObject`

Shorthand for creating application/json responses.

const res = json({
  description: 'Response description',
  headers,
  links,
  schema,
  examples,
  encoding,
});

// same as
const res = {
  description: 'Response description',
  headers,
  links,
  content: {
    'application/json': {
      schema,
      examples,
      encoding,
    },
  },
};