メインコンテンツまでスキップ

OpenAPI

Zeltはcontrollerから自動的にOpenAPI 3.1仕様を生成します — デコレータやアノテーションは不要です。

概要​

@zeltjs/openapi パッケージは、build時にcontrollerのメソッドシグネチャを解析し、標準的なOpenAPI 3.1仕様を生成します。

インストール​

npm install @zeltjs/openapi

Valibot adapterと併用する場合​

Valibotからschemaを生成する場合は、@zeltjs/validator-valibot/openapi を使い、@valibot/to-json-schema をインストールしてください:

npm install @zeltjs/openapi @valibot/to-json-schema

:::tip バージョン互換性 @valibot/to-json-schema は valibot のバージョンと合わせる必要があります。詳細は Validation - Installation を参照してください。 :::

設定​

プロジェクトルートに zelt.config.ts ファイルを作成します:

export default defineConfig({
  controllers: ['./src/**/*.controller.ts'],
  dist: './generated',
  tsconfig: './tsconfig.json',
});

設定オプション​

オプション型説明
controllersstring[]controllerファイルを見つけるためのglobパターン
diststring生成されたファイルの出力ディレクトリ
tsconfigstringtsconfig.jsonへのパス(OpenAPI生成に必須)

Controllerは、globパターンに一致するファイルをスキャンし、@Controller デコレータを持つクラスを検出することで自動的に発見されます。

OpenAPI仕様の生成​

単発ビルド​

pnpm zelt-openapi build

これにより <dist>/openapi.json が生成されます。

Watchモード​

pnpm zelt-openapi watch

controllerが変更されるたびに継続的に再生成します。

npmスクリプト​

package.json に追加します:

{
  "scripts": {
    "generate": "zelt-openapi build",
    "generate:watch": "zelt-openapi watch"
  }
}

生成されるopenapi.json​

標準的なOpenAPI 3.1仕様:

{
  "openapi": "3.1.0",
  "info": {
    "title": "zelt app",
    "version": "0.0.0"
  },
  "paths": {
    "/hello/{name}": {
      "get": {
        "parameters": [...],
        "responses": {...}
      }
    }
  },
  "components": {
    "schemas": {...}
  }
}

仕組み​

Zeltは Scramble に着想を得た「ゼロアノテーション」アプローチを使用します:

  1. 静的解析 — build時にcontrollerのメソッドシグネチャを解析する
  2. 型抽出 — TypeScriptの型からrequest/responseの型を抽出する
  3. Schema生成 — TypeScriptの型をOpenAPI用のJSON Schemaに変換する

これにより、あなたのランタイムコードはクリーンなまま保たれます — validationのためにすでに書いているもの以外の、デコレータやschema定義は不要です。