TypeSpec

TL;DR

API の仕様を記述するために Microsoft が開発した DSL。構文は TypeScript とほとんど同じで、拡張子は .tsp。

なぜ必要か

1 つの定義から、OpenAPI（REST API）や Protocol Buffers（gRPC）など、複数の形式の仕様を出力できる。公式サイトでは、データ設計を先に行い、そこからスキーマ、API 仕様、クライアントやサーバーのコード、ドキュメントを生成する使い方を挙げている。

仕組み

公式に用意されている出力先は、OpenAPI 3.0、JSON Schema 2020-12、Protobuf の .proto ファイルである。独自のエミッタ（出力処理）やデコレータを作って拡張することもできる。tsp init でテンプレートからプロジェクトを作れる。

例

JSON Schema を出力する定義の例。

import "@typespec/json-schema";
 
using JsonSchema;
 
@jsonSchema
namespace Schemas;
 
model Person {
  name: string;
  address: Address;
  @uniqueItems nickNames?: string[];
  cars?: Car[];
}
 
model Address {
  street: string;
  city: string;
  country: string;
}
 
model Car {
  kind: "ev" | "ice";
  brand: string;
  @minValue(1900) year: int32;
}

関連

• OpenAPI
• Protocol Buffers
• TypeScript

出典

• TypeSpec