fix: move openapi-types to dependencies

[shinagawa-web]

概要

openapi-types が pkgs/typed-api-spec の devDependencies にしか入っておらず、実際には公開APIの型シグネチャの一部として必要になっていた問題を修正します。

問題

src/core/openapi/openapi.ts ・ spec.ts は toOpenApiDoc や OpenApiSpecSchema などの公開関数・型のシグネチャで openapi-types の OpenAPIV3_1 を直接使っています。これらは src/core/index.ts 経由で @notainc/typed-api-spec/core から、さらに src/index.ts の export * from "./core" 経由でパッケージ root からも公開されています。

つまり @notainc/typed-api-spec(root)や @notainc/typed-api-spec/core を使う消費者のTypeScriptは、これらの型を解決する際に .d.ts 内の import { OpenAPIV3_1 } from "openapi-types" を辿る必要があります。しかし openapi-types は devDependencies にしかなく、dependencies/peerDependencies に無いため、消費者の node_modules に自動でインストールされる保証がありません。型は使えると宣言しているのに、その型を構成するパッケージ自体が存在しない可能性がある、という状態でした。

対応

openapi-types を devDependencies から dependencies に移動しました。

openapi-types はランタイムコードを持たない型定義のみのパッケージで、zod/valibot/express/fastify/msw のように「消費者が実行時の同一インスタンスを共有する必要がある」という peerDependencies にする理由が当てはまりません。パッケージが動作・型解決するために常に必要な @standard-schema/spec や json-schema などと同じ扱いとして dependencies に置くのが妥当と判断しました。

影響

利用者側の対応は不要です(消費者が明示的に openapi-types をインストールしていなくても、@notainc/typed-api-spec のインストール時に自動で入るようになる、という改善のみ)。

[shinagawa-web]

@claude
SKILLは以下を参考にしてください。
https://raw.githubusercontent.com/shokai/agent-skills/refs/heads/main/plugins/sanity-review/skills/sanity-review/SKILL.md

PRのレビューをしてください

[claude]

Claude finished @shinagawa-web's task in 2m 15s —— View job

---

PR レビュー: fix: move openapi-types to dependencies

参考いただいた sanity-review SKILL の観点(PR 説明と実装の整合性 / 判断の妥当性 / バグ・脆弱性 / 見落とし)を踏まえてレビューしました。

• SKILL ガイドを取得
• 変更内容の確認 (pkgs/typed-api-spec/package.json)
• openapi-types の利用箇所を精査
• 公開 API 型シグネチャの依存関係を検証
• レビュー結果を投稿

---

総合判定: LGTM ✅

差分が最小で、PR 説明の主張と実際のコード・パッケージ構成が完全に一致しています。判断根拠(peerDependencies ではなく dependencies を選ぶ理由)も明示されており妥当です。

PR 説明の整合性チェック

PR 説明の主張を実コードで検証しました。すべて事実と一致しています。

PR 説明での主張	実コードでの確認
openapi-types が devDependencies にしかない	変更前 package.json:33 で確認
src/core/openapi/openapi.ts の公開型で OpenAPIV3_1 を使用	openapi.ts:1 で import、OpenApiSpecSchema などの型定義および toOpenApiDoc (openapi.ts:159-162) が OpenAPIV3_1.Document / PathItemObject を直接参照
spec.ts の公開型で OpenAPIV3_1 を使用	spec.ts:7 で import、DefineOpenApiEndpoint(ServerObject)/ OperationObject(OpenAPIV3_1.OperationObject) / ToOpenApiResponse(ResponseObject) が直接参照
これらが src/core/index.ts → src/index.ts 経由で外部公開されている	src/core/index.ts:9 の export * from "./openapi"、src/index.ts:1 の export * from "./core" を確認

つまり公開 .d.ts 内で import { OpenAPIV3_1 } from "openapi-types" を辿る必要があるのに、その openapi-types が消費者側の node_modules に自動で入る保証がなかった、という問題把握は正確です。

判断(dependencies vs peerDependencies)の妥当性

• openapi-types は型定義のみのパッケージで、ランタイム値の共有インスタンスが問題になりません。したがって zod / express / msw のような peerDependencies にする動機(同一インスタンス共有・重複回避)は該当しません。
• 一方で「型解決に常に必要」なので、動的 import で回避されている zod-openapi(optionalDependencies)や @valibot/to-json-schema(peerDependencies)とは扱いを分ける必要があり、@standard-schema/spec / json-schema と同列で dependencies に置くのが自然です。
• 既存 package.json の他エントリと分類が整合しており、方針として一貫しています。

気づいた細かい点(いずれもこの PR のスコープ外・ブロッカーではありません)

1. リリース時のバージョン戦略: 消費者側のインストール挙動が変わる(未指定でも自動で入る)ため、公開時は最低でも patch/minor バンプが望ましいです。破壊的変更ではないので minor で十分。
2. 将来的な選択肢: openapi-types の型を薄くラップして再 export し、公開 API から openapi-types を直接参照しない構造にすれば、依存を完全に内部化できます(現状で困っていなければ後回しでOK)。
3. バージョンレンジ ^12.1.3: openapi-types はメジャーで破壊的変更を入れる運用なので caret で問題なし。将来 v13 が出た際は明示的な追従が必要ですが、これは既存慣行通り。
4. openapi-valibot.test.ts / openapi-zod.test.ts も openapi-types を import していますが、これはテストコードなので dependencies として解決されて問題ありません(devDependencies に戻す必要なし)。

見落とし(sanity check)

• 公開 API 側から openapi-types を参照している他のエントリポイント(./core 以外の ./express, ./fastify, ./fetch, ./msw, ./json サブパス)についても念のため確認しましたが、これらは ./core を経由するため同じ修正で解決されます。追加対応は不要です。
• monorepo ルート側の package.json に openapi-types の記載はなく、pkgs/typed-api-spec に閉じた修正になっているのも意図通りです。

---

問題把握・判断・実装が三位一体で通っており、意図した最小変更として綺麗にまとまっています。マージ可能と考えます。
| Branch: fix/openapi-types-runtime-dependency