Azure REST APIの仕様PRを出すチームがまず押さえるべき結論は、新しいAPIバージョンを手書きのOpenAPI/Swaggerだけで追加するPRは、TSP-REQUIRED-V1によりBlocking指摘の対象になり得るという点です。一方で、既存のAPIバージョンディレクトリ内にある手書きSwaggerの保守編集は、明示的に許可されています。つまり今回の更新は、Azure REST APIを利用するアプリ側の破壊的変更ではなく、Azure REST API仕様を作成・レビューする側のワークフロー変更として理解するのが適切です。(GitHub)
2026年5月5日時点で確認すべきポイントは、PR作成前に「その変更は新しいAPIバージョンなのか」「TypeSpecから生成されたことをレビュアーが判断できるか」「既存バージョンの保守編集に該当するか」を切り分けることです。新規バージョンであれば、main.tsp、tspconfig.yaml、.tspファイルの差分、または生成Swaggerのx-typespec-generatedなど、TypeSpec由来であることを示す材料をPR内に残す必要があります。(GitHub)
Azure REST APIで追加されたTSP-REQUIRED-V1とは
TSP-REQUIRED-V1は、Azure REST API仕様リポジトリのレビューで使われるARM API Reviewer agentに追加されるルールです。目的は、新しいAPIバージョンを追加する際に、手書きOpenAPI/Swaggerだけで仕様を増やすPRを検出し、TypeSpecでの作成を促すことです。PR #42846では、ARM API Reviewer agentが新しいAPIバージョンディレクトリを確認する際に、このルールを適用する変更が説明されています。(GitHub)
TypeSpecは、API仕様、クライアントコード、サーバー側コードなどを生成するためにAPIを定義する言語です。Microsoft Learnでは、TypeSpecを使うことでAPIガイドラインに沿った再利用可能なコンポーネントを作り、OpenAPIエミッターによって既存ツールとの互換性を保てると説明されています。Azureの文脈では、TypeSpec仕様を元にOpenAPI 2.0、いわゆるSwaggerのAPIドキュメントを生成する流れが示されています。(Microsoft Learn)
今回の更新で重要なのは、単に「TypeSpecを推奨する」ではなく、新しいAPIバージョンに対してTypeSpecを必須の作成形式として扱うレビュー観点が明文化されたことです。ルール定義では、Azure TypeSpecライブラリを使ったTypeSpecが、control planeとdata planeの両方の新しいAPIバージョンに必要な作成形式として記載されています。(GitHub)
何が変わるのか
今回のAzure REST API documentation updateで見るべき変更点は、レビュー時の判断基準がより具体化されたことです。従来からTypeSpecへの移行方針は示されていましたが、TSP-REQUIRED-V1では「どのPRをBlockingとして指摘するか」「どのPRは指摘しないか」「何をTypeSpec由来の証跡と見るか」が明確になっています。
| 観点 | 変更の要点 | 実務上の意味 |
|---|---|---|
| 新しいAPIバージョン | 手書きSwaggerだけで新規APIバージョンを追加するとBlocking指摘の対象 | 既存フォルダをコピーして日付だけ変える運用は危険 |
| 既存APIバージョンの保守 | 既存ディレクトリ内の手書きSwagger編集は許可 | 過去バージョンを一律でTypeSpec化する必要はない |
| TypeSpec由来の判定 | main.tsp、tspconfig.yaml、.tsp差分、x-typespec-generatedなどを確認 | 生成元がPR上で分かるようにする必要がある |
| レビュータイミング | ARM API ReviewerのBreaking Change Comparisonの流れで確認 | 既存バージョン比較と同時に新規バージョン判定が入る |
| CIとの関係 | 自動的にブロックする決定的CIチェックは別PRで開発中 | 現時点ではレビュー指摘として先に運用される可能性がある |
PR #42846では、openapi-review.instructions.mdにTSP-REQUIRED-V1の定義を追加し、armapi-review.instructions.mdとtypespec-review.instructions.mdにも参照を追加する変更が含まれています。また、ARM API Reviewer agentのStep 3、つまりBreaking Change Comparisonの流れにTypeSpec必須チェックを組み込むと説明されています。(GitHub)
対応が必要な人と影響範囲
この変更の影響を受けるのは、Azure REST APIを呼び出す一般のアプリケーション開発者ではなく、主にAzure REST API仕様を作成・管理するチームです。特に、Azureサービスの新しいAPIバージョンをazure-rest-api-specsに追加する担当者は、PR作成前にTypeSpec対応状況を確認する必要があります。
| 対象者 | 影響 | 取るべき対応 |
|---|---|---|
| AzureサービスのAPI仕様作成者 | 新規APIバージョンを手書きSwaggerだけで追加すると指摘される可能性 | 新規バージョンはTypeSpecで作成し、生成Swaggerをチェックイン |
| ARM / Resource Manager API担当者 | ARM API ReviewerでTSP-REQUIRED-V1が見えるようになる | resource-manager配下の新規バージョン追加時に必ず確認 |
| data plane API担当者 | ルール定義上はdata planeの新規APIバージョンも対象 | 自チームのレビュー経路で同ルールがどう適用されるか確認 |
| APIレビュー担当者 | 判断基準が明文化される | Blocking対象とFalse positiveを切り分ける |
| SDK・ドキュメント生成担当者 | TypeSpec生成物が前提になりやすい | TypeSpec更新、生成Swagger、SDK生成の流れをそろえる |
| Azure REST API利用者 | 公開済みAPIの呼び出し方法自体には直接影響しにくい | 仕様更新の品質向上として捉えればよい |
Azure REST API仕様リポジトリは、Microsoft AzureのREST API仕様の正式なソースとして位置付けられています。そのため、ここでの作成形式やレビュー基準の変更は、将来のSDK生成、APIリファレンス生成、APIレビューの通過しやすさに影響します。(GitHub)
Blocking指摘されるPRとされないPR
TSP-REQUIRED-V1で最も誤解しやすいのは、「手書きSwaggerがすべて禁止される」と受け取ってしまう点です。実際には、対象は新しいAPIバージョンディレクトリに、TypeSpec由来と判断できない手書きOpenAPI/Swaggerを追加するケースです。既存バージョンのメンテナンスは対象外として明示されています。(GitHub)
Blocking指摘されやすい例
| PRの内容 | 判定の目安 | 理由 |
|---|---|---|
stable/2026-05-01/を新規作成し、Swagger JSONだけを追加 | Blocking対象になりやすい | 新規APIバージョンなのにTypeSpec由来の証跡がない |
既存のstable/2025-10-01/をコピーしてstable/2026-05-01/にし、JSONを手編集 | Blocking対象になりやすい | 新しいバージョンディレクトリで手書きSwaggerを追加している |
| 新しいpreviewバージョンをOpenAPI JSONだけで追加 | Blocking対象になりやすい | stableだけでなくpreviewも新規APIバージョンとして扱われる |
.tspソースを更新せず、生成Swaggerだけを追加 | Blockingまたはレビュー指摘のリスク | 生成元がPR上で判断しにくい |
指摘されない、または指摘対象外になりやすい例
| PRの内容 | 判定の目安 | 理由 |
|---|---|---|
| 既存のAPIバージョンディレクトリ内のSwaggerを修正 | 指摘対象外 | 既存バージョン内の手書きSwagger保守は許可されている |
新しいAPIバージョンをTypeSpecから生成し、Swaggerにx-typespec-generatedがある | 指摘対象外になりやすい | TypeSpec生成物と判断できる |
同じサービスフォルダにmain.tspとtspconfig.yamlがあり、そこから新規バージョンを出力 | 指摘対象外になりやすい | sibling TypeSpec projectとして判断できる |
PRで同じサービスフォルダ配下の.tspファイルを追加・更新 | 指摘対象外になりやすい | TypeSpecソース変更が確認できる |
examples、readme.md、tspconfig.yaml、.tspのみの変更 | ルール上は指摘しない | 新規APIバージョン内の手書きSwagger追加ではない |
ルール定義では、TypeSpec由来と判断するシグナルとして、同じサービスフォルダ内のTypeSpecプロジェクト、生成Swaggerのトップレベルx-typespec-generated、同じサービスフォルダ配下の.tsp追加または更新が挙げられています。いずれも見つからない場合、新しいAPIバージョンは手書きOpenAPIとして扱われ、TSP-REQUIRED-V1のBlocking指摘になります。(GitHub)
PR作成前に確認すべき判断フロー
新しいAzure REST API仕様を出す前に、次の順番で確認すると判断ミスを減らせます。
| 確認順 | チェック項目 | 判断基準 |
|---|---|---|
| 1 | PRでstableまたはpreview配下に新しいAPIバージョンディレクトリを作っているか | 作っていなければ、多くの場合TSP-REQUIRED-V1の中心対象ではない |
| 2 | そのディレクトリはbase branchに存在しないか | 存在しなければ「新しいAPIバージョン」と見なされる |
| 3 | 新しいディレクトリにOpenAPI/Swagger JSONを追加しているか | 追加していればTypeSpec由来の証跡確認が必要 |
| 4 | 同じサービスフォルダにmain.tspとtspconfig.yamlがあるか | ある場合はTypeSpecプロジェクトとして説明しやすい |
| 5 | Swaggerにx-typespec-generatedがあるか | ある場合は生成Swaggerとして判断されやすい |
| 6 | PRで.tspファイルを追加・更新しているか | ある場合はTypeSpecソース変更として判断されやすい |
| 7 | どのシグナルもないか | 新規バージョンをTypeSpecで作り直すべき |
手元で差分を確認する場合は、次のようなコマンドで「新しいバージョンディレクトリ」と「TypeSpecの証跡」を見ると効率的です。環境やブランチ名はチームの運用に合わせて読み替えてください。
git fetch origin main
git diff --name-status origin/main...HEAD -- specification
find specification/<service-folder> -name main.tsp -o -name tspconfig.yaml
grep -R '"x-typespec-generated"' specification/<service-folder>この確認で「新しいAPIバージョンのSwagger JSONはあるが、TypeSpecプロジェクトも.tsp差分もx-typespec-generatedもない」と分かった場合、そのままPRを出すとBlocking指摘を受ける可能性が高くなります。先にTypeSpecソースを整備し、tsp compile .で生成したOpenAPIをチェックインする流れに切り替えるべきです。(GitHub)
新しいAPIバージョンをTypeSpecで出すときの実務ポイント
TSP-REQUIRED-V1への対応は、「Swaggerを出さない」ことではありません。Azure REST API仕様リポジトリでは、TypeSpecをソースとして使い、生成されたOpenAPI/Swaggerをチェックインする流れが前提になります。PR #42846のルール定義でも、TypeSpecで作成し、tsp compile .で生成されたOpenAPIをTypeSpecソースと一緒にチェックインすることが修正方針として示されています。(GitHub)
実務では、次の点をPR前チェックに入れてください。
| チェック項目 | 確認内容 |
|---|---|
| TypeSpecプロジェクト | 同じサービスフォルダにmain.tspとtspconfig.yamlがあるか |
| Azure TypeSpecライブラリ | ARMなら@azure-tools/typespec-azure-resource-managerなど、対象に合うAzure TypeSpecライブラリを使っているか |
| 生成先 | tspconfig.yamlの出力先が追加したいAPIバージョンディレクトリと対応しているか |
| 生成物 | 生成Swaggerにx-typespec-generatedなどの判定材料があるか |
| PR差分 | .tspソース、設定、生成Swagger、examplesの関係が説明できるか |
| 手作業修正 | 生成Swaggerを手で直していないか。直したくなった場合はTypeSpec側を修正する |
| レビュー説明 | PR本文に「新APIバージョンはTypeSpecから生成」と明記しているか |
特に注意したいのは、生成SwaggerだけをPRに入れてTypeSpecソースを入れ忘れるケースです。レビュー担当者やエージェントから見ると、TypeSpecで生成したのか、既存Swaggerをコピーして手で直したのか判断できません。TSP-REQUIRED-V1は「TypeSpecで書いたつもり」を見るのではなく、PR上で確認できる証跡を見ます。
既存の手書きSwaggerはすぐ移行すべきか
既存バージョンの手書きSwaggerを、今回の更新だけを理由にすべてTypeSpecへ移行する必要はありません。ルール定義では、base branchにすでに存在するAPIバージョンディレクトリ内の手書きOpenAPIの編集は許可され、指摘しないと明記されています。(GitHub)
ただし、次の新しいAPIバージョンを出す予定があるサービスでは、早めにTypeSpec移行の計画を立てるべきです。既存の手書きSwaggerを保守し続けながら新バージョンだけTypeSpec化すると、ソースの二重管理や差分確認が難しくなる場合があります。
おすすめの進め方は次の通りです。
| 手順 | 作業 | 目的 |
|---|---|---|
| 1 | 既存APIバージョンと次回リリース予定を棚卸しする | TypeSpec対応が必要なタイミングを把握する |
| 2 | 次に追加するAPIバージョンをTypeSpec化の起点にする | 既存資産を無理に全面移行せず、影響を限定する |
| 3 | TypeSpecから生成したSwaggerと既存Swaggerの差分を確認する | 意図しないAPI変更を防ぐ |
| 4 | 変換PRと新APIバージョン追加PRを分ける | レビューで「移行」と「機能追加」が混ざるのを避ける |
| 5 | チームのPRテンプレートにTSP-REQUIRED-V1確認項目を追加する | 属人的な確認漏れを減らす |
Microsoft Learnでは、既存OpenAPI仕様をTypeSpecへ移行できることや、TypeSpecからOpenAPI仕様、クライアントコード、サーバー側コードなどを生成できることが説明されています。新規APIバージョンのたびに手作業でSwaggerを増やすより、TypeSpecをソースにして生成物を管理するほうが、長期的にはレビュー・SDK生成・ドキュメント生成の整合性を保ちやすくなります。(Microsoft Learn)
失敗しやすいポイント
TSP-REQUIRED-V1対応でよく起きる失敗は、TypeSpecそのものの理解不足よりも、PR上での見え方にあります。レビューエージェントは、PR差分とbase branchとの差を見て判断するため、「チーム内ではTypeSpecで生成したと分かっている」だけでは不十分です。
| 失敗例 | なぜ問題になるか | 対策 |
|---|---|---|
| 既存Swaggerをコピーして日付だけ変更する | 新しいAPIバージョンの手書きSwagger追加に見える | TypeSpecソースを作成し、生成Swaggerとして追加する |
| TypeSpecソースが別フォルダにある | sibling TypeSpec projectとして検出されにくい | 同じサービスフォルダ配下の構成にそろえる |
生成Swaggerにx-typespec-generatedがない | TypeSpec生成物と判断しにくい | エミッター設定と生成結果を確認する |
.tsp差分なしでSwaggerだけを追加する | 手書き追加と区別できない | .tspソースや設定の更新もPRに含める |
| 既存バージョン修正と新バージョン追加を同じPRに混ぜる | レビュー観点が複雑になる | 可能ならPRを分割する |
| 「CIがまだ開発中だから大丈夫」と考える | agent側のレビュー指摘は先に出る可能性がある | PR本文と差分でTypeSpec対応を明確にする |
| 手書きSwaggerをすべて禁止と誤解する | 不要な移行作業が増える | 既存バージョンの保守編集は許可される点を共有する |
PR #42846では、TSP-REQUIRED-V1は決定的CIチェックの「agent-side companion」として説明されており、関連するPR #42823では新しいAPIバージョンにSwaggerを追加するPRをブロックするCIチェックが扱われています。つまり、現段階ではレビュー指摘として見えていても、将来的にはCIでより機械的に止まる可能性を前提に準備したほうが安全です。(GitHub)
レビュー担当者が見るべき確認観点
レビュー担当者は、単に「TypeSpecかどうか」を見るのではなく、誤検出を避ける観点も持つ必要があります。ルール定義では、既存ディレクトリ内の手書きSwagger更新、TypeSpecから生成された新規バージョン、examplesやreadme.mdなどだけの変更を指摘しないようにするFalse-positive avoidanceが記載されています。(GitHub)
レビュー時は、次の順に確認すると判断が安定します。
| 確認観点 | 見る場所 | 判断 |
|---|---|---|
| 新規APIバージョンか | PR差分とbase branchのディレクトリ | baseにないversion folderなら新規 |
| 対象がSwagger JSONか | specification/**/{resource-manager,data-plane}/**/{stable,preview}/配下 | 新規Swagger追加なら要確認 |
| TypeSpecプロジェクトがあるか | 同じサービスフォルダ | main.tspとtspconfig.yamlを確認 |
| 生成Swaggerか | JSONトップレベル | x-typespec-generatedを確認 |
.tsp差分があるか | PR差分 | 同じサービスフォルダの.tsp追加・更新を確認 |
| 既存バージョン保守か | version folderの存在 | 既存フォルダならBlockingにしない |
| examples等だけか | 変更ファイル種別 | examples、readme、tspconfig、.tspのみなら原則指摘しない |
レビューコメントを書く場合は、「TypeSpec必須です」だけではなく、どの条件に該当したのかを明確にすると修正が早くなります。たとえば、「このPRはbase branchに存在しないstable/2026-05-01を追加していますが、同じサービスフォルダにTypeSpecプロジェクト、.tsp差分、x-typespec-generatedのいずれも確認できないため、TSP-REQUIRED-V1のBlocking対象です」のように書くと、PR作成者が次に何を直すべきか分かります。
よくある疑問
既存の手書きSwaggerはもう編集できないのか
編集できます。TSP-REQUIRED-V1は、新しいAPIバージョンディレクトリに手書きOpenAPI/Swaggerを追加するケースを対象にしています。すでにbase branchに存在するAPIバージョンディレクトリ内の手書きSwagger更新は許可されています。(GitHub)
data plane APIも対象なのか
ルール定義では、TypeSpecはcontrol planeとdata planeの両方の新しいAPIバージョンに必要な作成形式とされています。ただし、今回のPRはARM API Reviewer agent側の変更として説明されているため、実際のレビュー経路やCI適用状況は、対象リポジトリとPRの最新状態で確認してください。(GitHub)
Azure REST APIを利用するアプリケーションに影響はあるのか
通常、直接の影響はありません。今回の更新は、公開済みのAzure REST APIエンドポイントの呼び出し方法を変えるものではなく、Azure REST API仕様を作成・レビューするプロセスに関する変更です。ただし、仕様の作成形式がTypeSpecに寄ることで、将来的なSDK生成やAPIドキュメントの整合性には影響し得ます。
x-typespec-generatedがなければ必ずBlockingになるのか
必ずではありません。x-typespec-generatedはTypeSpec由来と判断するシグナルの一つです。同じサービスフォルダにmain.tspとtspconfig.yamlを持つTypeSpecプロジェクトがある、またはPRで.tspファイルを追加・更新している場合も、TypeSpec由来の証跡として扱われます。(GitHub)
PR #42823との違いは何か
PR #42846は、ARM API Reviewer agentがレビュー時にTSP-REQUIRED-V1を指摘できるようにする変更です。一方、PR #42823は、新しいAPIバージョンにSwaggerを追加するPRを自動的にブロックする決定的CIチェックとして言及されています。PR #42846の説明では、agent ruleはレビューコメント上でseverity、fix、rule IDを示す説明的な表面として機能するとされています。(GitHub)
まず取るべき対応
Azure REST API仕様を扱うチームは、次の3点をすぐに確認してください。
1つ目は、直近で新しいAPIバージョンを追加するPRがあるかどうかです。ある場合は、手書きSwaggerだけの追加になっていないかを確認します。
2つ目は、TypeSpecプロジェクトと生成Swaggerの関係がPR上で分かるかどうかです。main.tsp、tspconfig.yaml、.tsp差分、x-typespec-generatedのいずれかが確認できる状態にしておくと、レビューでの説明がスムーズになります。
3つ目は、既存バージョンの保守編集と新規バージョン追加を混同しないことです。既存バージョンの修正は引き続き許可されますが、新規バージョンはTypeSpecで作成する前提に切り替える必要があります。
今回のTSP-REQUIRED-V1は、Azure REST API仕様の品質と一貫性を保つためのレビュー基準です。次のPRからは、「新規APIバージョンか」「TypeSpec由来と判断できるか」「既存バージョン保守なのか」をPR作成前に確認し、必要であればTypeSpecソースの整備から着手するのが最も安全です。
コメント