Tspec

Appearance

On this page

Generating Document ​

On this page, we will learn how to generate OpenAPI Spec and serve it with Swagger UI using Tspec.

CLI Usage ​

generate ​

Generate OpenAPI Spec from TypeScript types.

Usage

bash
yarn tspec generate [options]
bash
npx tspec generate [options]
bash
pnpx tspec generate [options]
options
OptionTypeDescriptionExample
--specPathGlobs [path]string[]Path of TypeScript files which you want to generate OpenAPI schemasrc/**/*.ts
--tsconfigPath [path]stringPath of tsconfig./tsconfig.json
--outputPath [path]stringPath of output OpenAPI schema./generate/openapi.yaml
--specVersion [version]numberVersion to use for OpenAPI schema (Currently supports only 3)3
--openapiTitle [title]stringtitle property of OpenAPI schemaTspec
--openapiVersion [version]stringversion property of OpenAPI schema1.0.0
--openapiDescription [description]stringdescription property of OpenAPI schemaThis is Tspec API
--debug [true / false]booleanPrint debug information for Tspecfalse
--ignoreErrors [true / false]booleanWhether ignore errors in Tspec or notfalse

server ​

Start Tspec server for display OpenAPI Spec with Swagger UI.

Usage

bash
yarn tspec server [options]
bash
npx tspec server [options]
bash
pnpx tspec server [options]
options

You can also use the CLI options for generate command.

OptionTypeDescriptionExample
--port [port]numberSpecify port number for Tspec server7080
--proxyHost [host]stringSpecify proxy host for Tspec serverhttps://tspec.org

Configuration file ​

You can also use configuration file for generate and server command.

Create tspec.config.json in your project root directory.

json
{
  "specPathGlobs": ["src/**/*.ts"],
  "tsconfigPath": "./tsconfig.json",
  "outputPath": "./generate/openapi.json",
  "specVersion": 3,
  "openapi": {
    "title": "Tspec API",
    "version": "0.0.1",
    "description": "This is Tspec API",
  },
  "debug": false,
  "ignoreErrors": true,
}

The type of configuration file is Tspec.GenerateParams

Programmatic Usage ​

generate ​

ts
import { generateTspec, Tspec } from 'tspec';

const options: Tspec.GenerateParams = {
  specPathGlobs: ['src/**/*.ts'],
  tsconfigPath: './tsconfig.json',
  outputPath: './generate/openapi.json',
  specVersion: 3,
  openapi: {
    title: 'Tspec API',
    version: '0.0.1',
    description: "This is Tspec API",
  },
  debug: false,
  ignoreErrors: true,
};

const openApiSpec = await generateTspec(options);

server ​

ts
import { initTspecServer, Tspec } from 'tspec';

const options: Tspec.InitTspecServerOptions = {
  specPathGlobs: ['src/**/*.ts'],
  tsconfigPath: './tsconfig.json',
  outputPath: './generate/openapi.json',
  specVersion: 3,
  openapi: {
    title: 'Tspec API',
    version: '0.0.1',
    description: "This is Tspec API",
  },
  debug: false,
  ignoreErrors: true,
  port: 3000,
  proxyHost: 'https://tspec.org',
};

initTspecServer(options);