Posted inDevelopment

TypeSpecでAPI設計をより「楽」に：数千行のOpenAPIファイル管理にさよならを

Development tutorial - IT technology blog
Development tutorial - IT technology blog

「手動OpenAPI」という悪夢

3,000行ものopenapi.yamlファイルを手動で書くことは、エンジニアの忍耐力を削る最短ルートです。もし、数十個のエンドポイントのうち一つのフィールドの更新を忘れ、フロントエンドがAPIを叩いた際にデータがドキュメント通りに返ってこないという「ちぐはぐな」経験をしたことがあるなら、その苦痛がわかるはずです。冗長で繰り返しの多いYAML構文や、スキーマの再利用が極めて困難な点は、複雑なマイクロサービスプロジェクトにおいて大きな障壁となります。

TypeSpecを本番環境に導入して6ヶ月、これがAPI-firstな開発プロセスにおける「救世主」であると確信しました。YAMLと格闘する代わりに、TypeScriptのような簡潔な構文でコードを書くだけで済みます。このツールは、SwaggerからClient SDKまで、あらゆるものを自動的に生成します。実際に私たちのチームでは、TypeSpecの導入により、バックエンドとフロントエンド間のデータ構造に関する打ち合わせ時間を最大70%削減できました。

TypeSpec：TypeScriptとAPI設計が融合する時

TypeSpecは、Microsoftが開発したサービス定義言語（IDL）です。API設計に特化したTypeScriptの別バージョンと考えると分かりやすいでしょう。わずか数行の簡潔なコードで、モデル、エンドポイント、およびデータの制約を定義できます。

TypeSpecの最大の強みは、Single Source of Truth（信頼できる唯一の情報源）を作成できる点にあります。一つの.tspファイルから、以下のような多様な形式を出力可能です：

  • Swaggerドキュメント用のOpenAPI 3.0/3.1
  • 入力データを検証するためのJSON Schema
  • 多言語対応のClient SDK（C#、Java、Python、TypeScript）
  • gRPCを使用するシステム向けのProtobuf

実践：5分で最初のAPIを構築する

始める前に、NodeJSがインストールされていることを確認してください。TypeSpecコンパイラのインストールは、npmコマンド一つで完了します：

npm install -g @typespec/compiler

次に、新しいプロジェクトを初期化します：

mkdir my-api-design && cd my-api-design
tsp init

テンプレートの選択を求められたら、@typespec/openapi3を選択してください。これは、標準化されたAPIドキュメントを作成するための最も一般的な選択肢です。

YAMLの代わりにTypeSpecでコードを書く

記事管理APIを設計してみましょう。TypeSpec’の構文が、JSONの括弧の山よりもいかに明快で整理されているかがわかるはずです：

import "@typespec/http";
import "@typespec/rest";
import "@typespec/openapi3";

using TypeSpec.Http;
using TypeSpec.Rest;

@service({
  title: "ブログサービス",
})
@server("https://api.itfromzero.com", "本番サーバー")
namespace Blog;

model Post {
  @visibility("read")
  id: string;

  @minLength(5)
  title: string;

  content: string;
  status: "draft" | "published";
  createdAt: utcDateTime;
}

@route("/posts")
interface Posts {
  @get list(): Post[];
  
  @post create(@body post: Post): Post | { @statusCode statusCode: 400, message: string };

  @get read(@path id: string): Post | { @statusCode statusCode: 404 };
}

上記のコードでは、@minLengthなどのバリデーションを含むmodel Postを定義しています。Postsインターフェースには、対応するHTTPメソッドが含まれています。YAMLのような煩わしいインデントに悩まされることはもうありません。

ドキュメント出力の自動化

設計が終わったら、以下のコマンドを実行するだけで、プロフェッショナルなopenapi.yamlファイルが生成されます：

tsp compile .

結果はtsp-outputディレクトリに出力されます。作業中にデータのフォーマットやJSONのチェックが必要な場合、私はよくtoolcraft.appを使用します。このツールは、VS Codeに拡張機能を入れすぎて動作を重くすることなく、生成されたJSONを素早く処理するのに役立ちます。

Client SDKとの「不一致」を解消する

バックエンドがフィールドを変更したのに、フロントエンドがそれを知らないというトラブルはよく起こります。TypeSpecでは、Emitterを使用してフロントエンド用のコードを自動生成できます。

TypeScript用のEmitterのインストールは非常に簡単です：

npm install @azure-tools/typespec-ts

その後、tspconfig.yamlファイルで設定を行います。コンパイルすると、TypeSpecはすべてのインターフェースとAPI呼び出し関数を生成します。フロントエンドチームはこのパッケージをインポートするだけで、正確なコード補完（IntelliSense）を利用でき、タイポによるミスはほぼゼロになります。

実プロジェクトから得た教訓

半年間の運用を経て、プロセスを最適化するための3つの重要な経験則を導き出しました：

  1. ドキュメントを「沈黙」させない： @docデコレータを使用して、各フィールドの詳細を記述しましょう。これらの説明はSwagger UIに直接表示され、他の開発者があなたに質問することなくAPIを理解する助けになります。
  2. すべてをモジュール化する： ErrorResponseやPaginationなどの共通モデルは、common.tspファイルにまとめましょう。これにより、コードの重複を避けながら、数十のマイクロサービスを管理できます。
  3. CI/CDに組み込む： Pull Requestのたびに自動的にtsp compileが実行されるように設定しましょう。.tspファイルにエラーがあればビルドが失敗し、誤ったドキュメントがシステムに反映されるのを防げます。

TypeSpecのリンティング（エラーチェック）機能は非常に強力です。誤って同じルートに2つのエンドポイントを定義してしまった場合、コンパイラが即座にエラーを報告します。デプロイしてからドキュメントの混乱に気づくのではなく、コードを書いている最中にミスを発見できるのです。

Lời kết

TypeSpecは単なる新しいツールではなく、システム設計に対する考え方を根本から変えるものです。設計図と実装の間のギャップを埋めてくれます。プロジェクトが小規模なスタートアップであれ、大規模なエンタープライズシステムであれ、TypeSpecへの投資は、プロジェクト規模が拡大した際の負担を大幅に軽減してくれるでしょう。手動でYAMLファイルを修正する時間はもう終わりにしましょう。今日からTypeSpecを試して、その違いを体感してください！

Share:
Tags: