openapi-to-typescript

openapi-to-typescript スキルの概要

openapi-to-typescript スキルは、OpenAPI 3.0 の JSON / YAML 仕様から TypeScript のインターフェース、エンドポイントのリクエスト / レスポンス型、さらに実行時の type guard までを生成するための、用途特化型のコード生成ワークフローです。すでに API 仕様書が手元にあり、長いカスタムプロンプトを毎回組み立てるよりも、実用的な TypeScript 出力を素早く得たい開発者に向いています。

openapi-to-typescript で実際にできること

openapi-to-typescript を使うべきなのは、「OpenAPI を理解したい」ときではなく、「既存の spec から型付き API コードを出したい」ときです。このスキルは実務寄りの手順で設計されています。まず spec を検証し、components/schemas と paths を読み取り、TypeScript を生成し、最後に types/api.ts のような妥当な保存先へ書き出します。

このスキルを入れるべき人

この openapi-to-typescript skill が合うのは、次のようなケースです。

• API を利用するフロントエンド / フルスタック開発者
• OpenAPI を公開していて、TS 向け成果物も欲しいバックエンドチーム
• Code Generation 用に再利用しやすいプロンプトパターンを求める AI 支援コーディング利用者
• 静的なインターフェースだけでなく runtime guard も重視するチーム

逆に、まだ有効な OpenAPI ファイルが存在しない場合や、生成したいものが型定義ではなく完全な client SDK である場合は、優先度は下がります。

汎用プロンプトではなくこれが選ばれる理由

汎用プロンプトだと、検証工程が抜けたり、対応バージョンの境界が曖昧だったり、schema の interface しか出ないまま終わることがよくあります。openapi-to-typescript はワークフローが明示されているぶん、導入しやすいのが強みです。

1. ファイルパスを確認する
2. OpenAPI 3.0.x か検証する
3. schema と endpoint を抽出する
4. 型を慎重にマッピングする
5. 出力をファイルへ書く

この流れがあることで当て推量が減り、レビューもしやすくなります。

インストール前に確認したい重要な制約

いちばん大きな判断ポイントは互換性です。

• OpenAPI 3.0.x のみ対応
• 入力は JSON または YAML 必須
• spec に paths が含まれている必要がある
• schema ベースの型生成を期待するなら components.schemas が必要

spec が不完全だったり、構造が崩れていたり、OpenAPI 3.1 の機能を前提にしている場合は、追加の整備や別ワークフローを見込んでおいたほうが安全です。

openapi-to-typescript スキルの使い方

openapi-to-typescript のインストール前提

スキル対応環境には次のコマンドでインストールします。

npx skills add softaworks/agent-toolkit --skill openapi-to-typescript

インストール後、最初に読むべき実用的なソースファイルは次の 2 つです。

• skills/openapi-to-typescript/SKILL.md
• skills/openapi-to-typescript/README.md

SKILL.md には実行手順がまとまっています。README.md は、このスキルが自分に合うか、どこまで機能をカバーしているか、どんな型パターンを扱えるかを把握するのに役立ちます。

openapi-to-typescript に必要な入力

openapi-to-typescript usage をうまく進めるには、次の情報を渡すのが理想です。

• OpenAPI ファイルの正確なパス
• 出力先のパス
• schema interface だけ欲しいのか、request/response の endpoint 型も必要か
• 生成型の命名ルールに関する希望
• 出力コードが合わせるべきリポジトリ規約

最低限これだけあれば動かせます。

• spec/openapi.yaml
• src/types/api.ts のような出力先

openapi-to-typescript を起動する最初のプロンプト

弱いプロンプト:

• “Convert this API to TypeScript”

強いプロンプト:

• “Use the openapi-to-typescript skill on spec/openapi.yaml. Validate that it is OpenAPI 3.0.x, extract components/schemas and endpoint request/response types from paths, generate TypeScript interfaces plus runtime type guards, and save the result to src/types/api.ts. If the spec is invalid, stop and tell me exactly what is missing.”

このプロンプトが機能しやすいのは、ファイル位置、対象範囲、出力先、失敗時の挙動まで明示できているからです。

実際の openapi-to-typescript ワークフロー

想定されている流れはシンプルです。

1. OpenAPI ファイルを見つける
2. openapi フィールドと主要セクションを検証する
3. components/schemas を読む
4. paths を解析して operation の入力 / 出力型を拾う
5. TypeScript を生成する
6. 保存先パスを確認する
7. ファイルを書き出す

この順番が大事なのは、多くの「OpenAPI から TS へ」変換が 2 の検証を飛ばしてしまい、壊れた spec からもっともらしいが誤った出力を作ってしまうからです。

生成前にこのスキルが検証すること

リポジトリ上のガイダンスでは、少なくとも次を確認するようになっています。

• openapi が存在し、3.0 で始まっていること
• paths が存在すること
• 抽出対象の型があるなら components.schemas が存在すること

これらのチェックに失敗した場合、正しい挙動は「その場で止まり、問題点を報告し、先に spec を修正する」ことです。実運用では入力の不備がよくあるので、これはコード生成ワークフローとしてかなり健全です。

期待できる出力内容

一般的な出力には次が含まれます。

• schema モデル向けの TypeScript interface
• endpoint 定義から導かれる request / response 型
• runtime type guard
• 配列、enum、union、intersection、および一般的な OpenAPI プリミティブの型変換

そのため、openapi-to-typescript for Code Generation は単なる interface 一括出力より実用性が高めです。

知っておきたい型マッピングの詳細

このスキルは、基本的な OpenAPI のプリミティブ型を次のようにマッピングします。

• string → string
• number → number
• integer → number
• boolean → boolean
• null → null

一見すると単純ですが、nullable フィールド、enum、配列、mixed schema をどこまで正確に扱えるかはレビューでよく見られるポイントです。必要なら、こうした区別を維持し、ゆるい型にまとめすぎないよう明示しておくと安心です。

リポジトリを読むならこの順番

本番用の spec に使う前に手早く確信を持ちたいなら、読む順番は次で十分です。

1. ワークフローと検証ルールを見るために SKILL.md
2. 対応出力と例を確認するために README.md

このスキルはコンパクトなので、リポジトリ全体を深掘りしなくても、まずは境界条件を素早く把握することに価値があります。

出力品質を上げる実践的なプロンプトパターン

次のような指示が有効です。

• “Generate types only from components/schemas; skip endpoint request/response types.”
• “Generate endpoint request and response types from paths and save them alongside schema interfaces.”
• “Keep naming stable and avoid unnecessary renaming unless a TypeScript identifier would be invalid.”
• “Tell me which schemas or operations could not be converted cleanly.”

こうした指定を入れると、レビューしやすくなり、diff も小さく保ちやすくなります。

実際の開発フローで openapi-to-typescript がはまる場面

実務では、openapi-to-typescript guide として次の流れが使いやすいです。

1. spec を検証または更新する
2. TS を専用ファイルへ生成する
3. 命名と optionality をレビューする
4. client、hooks、handlers などに型を組み込む
5. API spec が変わったら再生成する

生成ファイルは派生物として扱うのが基本です。そこに手作業の修正を重ねすぎると、再生成がつらくなります。

openapi-to-typescript スキル FAQ

openapi-to-typescript は初心者にも向いている？

はい。基本的な TypeScript が分かっていて、OpenAPI ファイルの場所を把握しているなら十分使えます。このスキルはプロンプト設計の手間を減らしてくれますが、元の spec を理解しなくてよくなるわけではありません。初心者が詰まりやすいのは、スキルそのものより、無効または不完全な OpenAPI のほうです。

openapi-to-typescript は OpenAPI 3.1 に対応している？

リポジトリのガイダンスを見る限り、このスキルの対象は OpenAPI 3.0.x です。spec が 3.1 の場合、きれいに動く前提で考えないほうがいいです。生成結果に依存する前に、ダウングレードするか、別のワークフローに寄せる必要があります。

schema を貼って AI に TS 生成させるより良い？

多くの場合は yes です。openapi-to-typescript skill には明確なワークフローと検証前提があるためです。単発の interface 変換ではなく、schema 型と endpoint を踏まえた request / response 型の両方を欲しいときに、より安定して使えます。

openapi-to-typescript を使わないほうがいいのはいつ？

次のケースでは見送る判断が妥当です。

• きちんとした OpenAPI spec がまだない
• 欲しいのが型定義ではなく完全な API client SDK
• API 記述が強くカスタムされていて、components/schemas と paths を軸に整理されていない
• チームが、より厳密なテンプレートを持つ別ジェネレーターに標準化している

runtime validation も生成される？

はい。ドキュメント上では interface だけでなく runtime type guard も出力対象に含まれています。未検証の API データに対して、コンパイル時の型だけに頼らず実行時チェックも入れたい場合に有効です。

openapi-to-typescript の利用で何が詰まりやすい？

よくあるブロッカーは次のとおりです。

• OpenAPI のバージョンが不正
• paths が欠けている
• components.schemas がない、または中身が薄い
• spec 内の命名が一貫していない
• 宣言されていない業務意味までスキルが推論してくれると期待してしまう

失敗の多くは生成処理そのものではなく、元ファイル側にあります。

openapi-to-typescript スキルを改善するには

長いプロンプトより、まず spec を整える

openapi-to-typescript の品質を最も大きく左右するのは、生成前の OpenAPI ドキュメントです。schema 名が明確で、required フィールドが正しく、endpoint response が一貫していれば、余計なプロンプト調整よりも最終的な TypeScript の質に効きます。

スコープをもっと具体的に指示する

「型を生成して」と頼むユーザーの意図は、実際には次の 3 パターンに分かれがちです。

• モデル interface だけ
• モデル interface と endpoint の request / response 型
• 型に加えて runtime guard まで

自分が必要としている範囲を明言してください。そうすることで、出力が実際のコードベースの要件に合いやすくなります。

変換しきれなかった箇所を出させる

価値の高い追加指示としておすすめなのが次です。

• “List any schemas, formats, or endpoints that could not be represented cleanly.”

これを入れると、完全再現できている前提で進めるのではなく、弱い部分を自分で確認できるため、結果への信頼度が上がります。

生成前に出力規約を決めておく

プロジェクト側に規約があるなら、先に伝えておくべきです。

• ファイルパス
• 命名スタイル
• schema ごとにまとめるか、operation ごとにまとめるか
• 生成コードを単独で完結させるか、既存の型レイヤーに import する前提にするか

これがないと、初回出力は技術的には正しくても、組み込みづらい形になりがちです。

よくある失敗パターンを先に見る

レビュー時によく見つかるのは次のような点です。

• optional フィールドが必要以上に緩く扱われている
• enum 値の確認が甘い
• union や intersection が 2 回目の見直しを要する
• endpoint response の型に error shape が反映されていない
• operation ID や schema title 由来で不自然な名前になっている

これはスキルを避ける理由ではなく、最初に重点チェックすべき場所だと考えるのが現実的です。

初回生成後の回し方

2 回目以降は、次の進め方が強いです。

1. 生成ファイルの命名と optionality を確認する
2. 重要な endpoint をいくつか spec と照合する
3. 不一致や曖昧な変換をメモする
4. 指示を絞って再実行する

フォローアップ例:

• “Regenerate using the same file, but preserve schema names exactly, keep separate request and response types per operation, and call out any ambiguous unions.”

チーム利用向けに openapi-to-typescript を整える

複数の開発者が openapi-to-typescript を使うなら、次を標準化しておくと効果的です。

• spec の置き場所
• 生成ファイルの保存先
• 使うプロンプトテンプレート
• 手動レビューが必要な出力セクション

ここを揃えておくと、単発の補助ツールではなく、Code Generation ワークフローの再現可能な一部として運用しやすくなります。