はじめる

このページでは、tspecを使用してTypeScript型からOpenAPI Specificationを生成し、Swagger UIで提供する方法を学びます。

インストール

Node.jsとTypeScriptがインストールされていることを前提に、新しいTypeScriptプロジェクトを作成します：

mkdir my-project
cd my-project

次に、tsconfig.jsonを初期化します：

tsc --init

package.jsonを初期化し、tspecをインストールします：

yarn

yarn init -y
yarn add tspec

npm

npm init -y
npm install tspec

pnpm

pnpm init -y
pnpm add tspec

ApiSpecの定義

Tspecはフレームワークに応じて複数の方法でAPI仕様を定義できます。

基本

import { Tspec } from "tspec";

/** JSDocで定義されたスキーマ説明 */
interface Book {
  /** JSDocで定義されたフィールド説明 */
  id: number;
  title: string;
  description?: string;
}

export type BookApiSpec = Tspec.DefineApiSpec<{
  paths: {
    '/books/{id}': {
      get: {
        summary: 'IDで本を取得',
        path: { id: number },
        responses: { 200: Book },
      },
    },
  }
}>;

Express

import { Request, Response } from 'express';
import { Tspec } from 'tspec';

interface Book {
  id: number;
  title: string;
}

// 型付きパラメータでExpressハンドラーを定義
export const getBook = async (
  req: Request<{ id: string }>,
  res: Response<Book>,
) => {
  res.json({ id: Number(req.params.id), title: 'Book Title' });
};

// handler型を使用してパラメータとレスポンスを自動生成
export type BookApiSpec = Tspec.DefineApiSpec<{
  paths: {
    '/books/{id}': {
      get: {
        summary: 'IDで本を取得',
        handler: typeof getBook,
      },
    },
  },
}>;

NestJS

import { Controller, Get, Param } from '@nestjs/common';

interface Book {
  id: number;
  title: string;
}

/**
 * Books APIコントローラー
 */
@Controller('books')
export class BooksController {
  /**
   * IDで単一の本を取得
   * @summary IDで本を取得
   */
  @Get(':id')
  findOne(@Param('id') id: string): Promise<Book> {
    return Promise.resolve({ id: Number(id), title: 'Book Title' });
  }
}

// ApiSpecを手動で定義する必要なし！
// `tspec generate --nestjs`でOpenAPI仕様を生成

OpenAPI仕様の生成

OpenAPI仕様を生成します：

基本 / Express

npx tspec generate --outputPath openapi.json

NestJS

npx tspec generate --nestjs --outputPath openapi.json

TIP

• 基本 / Express: Tspecは**/*.tsにマッチするすべてのファイルからTspec.DefineApiSpecを自動的に解析します。
• NestJS: --nestjsフラグを使用してコントローラーを直接解析します。デフォルトのglobはsrc/**/*.controller.tsです。
• 詳細はExpress連携とNestJS連携を参照してください。

生成されたOpenAPI仕様

（読みやすさのため、生成されたOpenAPI仕様はyaml形式で表示されます）

openapi: 3.0.3
info:
  title: Tspec API
  version: 0.0.1
paths:
  /books/{id}:
    get:
      operationId: BookApiSpec_get_/books/{id}
      tags:
        - Book
      summary: IDで本を取得
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      description: JSDocで定義されたスキーマ説明
      type: object
      properties:
        id:
          description: JSDocで定義されたフィールド説明
          type: number
        title:
          type: string
        description:
          type: string
      required:
        - id
        - title

OpenAPI仕様の提供

Swagger UIでOpenAPI仕様を提供します：

yarn

yarn tspec server --port 3000

npm

npx tspec server --port 3000

pnpm

pnpm tspec server --port 3000

ブラウザでhttp://localhost:3000/docsを開きます。

Swagger UIページが表示されます：

Schemasタブでスキーマ定義を確認できます。