ドキュメント生成

このページでは、Tspecを使用してOpenAPI仕様を生成し、Swagger UIで提供する方法を学びます。

CLI使用法

generate

TypeScript型からOpenAPI仕様を生成します。

使用法

yarn

yarn tspec generate [options]

npm

npx tspec generate [options]

pnpm

pnpx tspec generate [options]

オプション

オプション	型	説明	例
--specPathGlobs [path]	string[]	OpenAPIスキーマを生成するTypeScriptファイルのパス	src/**/*.ts
--tsconfigPath [path]	string	tsconfigのパス	./tsconfig.json
--configPath [path]	string	Tspec設定ファイルのパス	./tspec.config.json
--outputPath [path]	string	出力OpenAPIスキーマのパス	./generate/openapi.yaml
--specVersion [version]	number	OpenAPIスキーマのバージョン（現在3のみサポート）	3
--openapiTitle [title]	string	OpenAPIスキーマのtitleプロパティ	Tspec
--openapiVersion [version]	string	OpenAPIスキーマのversionプロパティ	1.0.0
--openapiDescription [description]	string	OpenAPIスキーマのdescriptionプロパティ	This is Tspec API
--debug [true / false]	boolean	Tspecのデバッグ情報を出力	false
--ignoreErrors [true / false]	boolean	Tspecのエラーを無視するかどうか	false
--nestjs [true / false]	boolean	NestJSコントローラーから生成（specPathGlobsをコントローラーファイルに使用）	false

server

Swagger UIでOpenAPI仕様を表示するTspecサーバーを起動します。

使用法

yarn

yarn tspec server [options]

npm

npx tspec server [options]

pnpm

pnpx tspec server [options]

オプション

generateコマンドのCLIオプションも使用できます。

オプション	型	説明	例
--port [port]	number	Tspecサーバーのポート番号を指定	7080
--proxyHost [host]	string	Tspecサーバーのプロキシホストを指定	https://tspec.org

設定ファイル

generateとserverコマンドに設定ファイルを使用することもできます。

プロジェクトルートディレクトリにtspec.config.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",
    "securityDefinitions": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "servers": [
      {
        "url": "https://api.example.com",
        "description": "Production server"
      }
    ]
  },
  "debug": false,
  "ignoreErrors": true,
  "nestjs": false
}

設定ファイルの型はTspec.GenerateParamsです。

プログラマティック使用法

generate

import { generateTspec, Tspec } from 'tspec';

const options: Tspec.GenerateParams = {
  specPathGlobs: ['src/**/*.ts'],
  tsconfigPath: './tsconfig.json',
  configPath: './tspec.config.json',
  outputPath: './generate/openapi.json',
  specVersion: 3,
  openapi: {
    title: 'Tspec API',
    version: '0.0.1',
    description: 'This is Tspec API',
    securityDefinitions: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
    servers: [
      {
        url: 'https://api.example.com',
        description: 'Production server',
      },
    ],
  },
  debug: false,
  ignoreErrors: true,
  nestjs: false, // NestJSモードはtrueに設定（specPathGlobsをコントローラーファイルに使用）
};

const openApiSpec = await generateTspec(options);

server

import { initTspecServer, Tspec } from 'tspec';

const options: Tspec.InitTspecServerOptions = {
  specPathGlobs: ['src/**/*.ts'],
  tsconfigPath: './tsconfig.json',
  configPath: './tspec.config.json',
  outputPath: './generate/openapi.json',
  specVersion: 3,
  openapi: {
    title: 'Tspec API',
    version: '0.0.1',
    description: 'This is Tspec API',
    securityDefinitions: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
    servers: [
      {
        url: 'https://api.example.com',
        description: 'Production server',
      },
    ],
  },
  debug: false,
  ignoreErrors: true,
  port: 3000,
  proxyHost: 'https://tspec.org',
};

initTspecServer(options);