TypeSpec は、API を設計するための強力で柔軟な言語です。 これにより、開発者は拡張可能でわかりやすい言語で API を定義できます。 このコンパイルでは、エミッターを使用して、API 仕様、クライアント コード、およびサーバー側 API コードを生成します。 TypeSpec は、Microsoft によって開発され、コミュニティによってサポートされている オープン ソース プロジェクト です。
TypeSpec を使用すると、API ガイドラインに準拠した、モジュール式の再利用可能なコンポーネントを作成できます。 標準の TypeSpec ライブラリには OpenAPI エミッタが含まれており、既存のツールやワークフローとの互換性を確保します。
TypeSpec はオープン ソース言語として、Azure API だけでなく任意の API を記述できます。 この多様性により、複雑で進化する環境で高品質の API を提供する必要がある API 開発者、アーキテクト、およびマネージャーにとって貴重なツールになります。
TypeSpec の利点
- API 開発を簡素化: API を定義するための明確で簡潔な方法を提供し、開発者がロジックと機能に集中できるようにします。
- デプロイの高速化: TypeSpec を使用すると、単一の API 定義から迅速なサービスとクライアント コードの生成が可能になり、デプロイが合理化され、一貫性が確保されます。
- コンプライアンスを確保: 再利用可能なコンポーネントを使用して、確立されたガイドラインと標準に準拠し、エラーや不整合を減らします。
- 互換性を強化: 既存のツールやワークフローとの互換性のために OpenAPI エミッターが含まれており、統合が容易になります。
- 拡張性をサポート: 柔軟で拡張可能で、さまざまなシナリオで API 定義のカスタマイズと拡張を可能にします。
- 移行を高速化: OpenApiMigration ツール を使用すると、TypeSpec への移行が容易にされ、より迅速に導入できます。
オープン ソース プロジェクトとして、TypeSpec はコミュニティの投稿とフィードバックから恩恵を受け、実際のユース ケースに基づいて継続的な改善を実現します。
API の設計は困難です
TypeSpec は、API の設計、ガバナンス、実装における一般的な課題に対処します。
- 複雑な仕様: API 仕様の記述、レビュー、保守は面倒な場合があります。 単純な API であっても、数百行の仕様コードが生成される可能性があります。
- プロトコルの多様性: 各プロトコルには独自の仕様形式があり、プロトコル間で共有された設計言語はありません。 この断片化により、開発プロセスが複雑になります。
- ガバナンスの問題: 統一された設計言語がないと、API の管理が困難になり、実装と品質に不整合が生じます。
- スケーラビリティの懸念: API または API バージョンの数が増えるにつれて、より多くのエンジニアリング チームが必要になり、調整の課題や非効率性につながる可能性があります。
これらの課題に対処することで、TypeSpec は API 設計プロセスを簡素化し、さまざまなプロトコル間の一貫性を確保し、全体的なガバナンスとスケーラビリティを強化します。
TypeSpec API 開発ワークフロー
次の図は、TypeSpec を使用した API の開発に関連する主要な段階を示しています。 プロセスは、最初から新しい API 仕様を作成するか、既存の OpenAPI 仕様から移行するかの 2 つのオプションから始まります。開始すると、API は、モジュール式の再利用可能なコンポーネントを使用して TypeSpec を使用して定義されます。 TypeSpec コンパイラは、堅牢な一連のエミッタを使用してこれらの定義を処理し、API 仕様、クライアント コード、およびサーバー側スタブ コードを自動的に生成します。 最後に、生成された成果物は既存のツールチェーンと統合され、スムーズで一貫性のあるワークフローが保証されます。
ワークフロー ステップ
| ステップ | 説明 |
|---|---|
| 始める | まず、TypeSpec を使用して新しい API 仕様を記述するか、既存の OpenAPI 仕様から移行します。 |
| TypeSpec 定義 | TypeSpec を使用して API を定義します。 再利用可能なコンポーネントは API を簡潔にし、ガイドラインに準拠していることを確認します。 |
| TypeSpec コンパイラ | コンパイラは TypeSpec 定義を処理して、コード生成用に準備します。 |
| 世代 | 専用エミッターは、API 仕様、クライアント コード、およびサーバー側スタブ コードを自動的に生成します。 |
| 統合 | 生成された出力は、既存の API ツールチェーンにシームレスに統合されます。 |
TypeSpec コンパイラからのパス:
TypeSpec コンパイラでは、必要に応じて OpenAPI 仕様、クライアント コード、およびサーバー側スタブ コードの出力を同時に生成できますが、プロジェクトの要件に基づいて各出力を個別にトリガーできます。
OpenAPI 仕様の生成
OpenAPI エミッターは、標準化された API 記述形式を生成します。Client-Side コードの生成
クライアント コード エミッターは、API を使用するためのコードを作成します。Server-Side スタブ コードを生成
サービス側エミッターは、API 実装を開始するためのサーバー スタブ コードを生成します。
TypeSpec を使用した包括的なコード生成
クライアント コードの生成
TypeSpec は、TypeSpec 定義から直接 API を使用するコードを自動的に作成することで、クライアント コードの生成を効率化します。 このプロセスでは、シームレスな統合を保証する標準ランタイム インターフェイス、特定のクライアント ニーズに合わせて出力を調整するためのカスタム コードの拡張性、開発スタック全体にわたる包括的な生成などの主要な機能を活用します。 その結果、開発者はアプリケーション間の一貫性を維持し、手動でのコーディング作業を減らし、API を既存のツールチェーンと迅速に統合しながら、より効率的でスケーラブルな開発ワークフローを楽しむことができます。
サポートされている言語:
- 。網
- ジャワ
- JavaScript
- Python（プログラミング言語）
サーバー コードの生成
TypeSpec では、TypeSpec 定義から直接サーバー側スタブ コードを生成できます。 これにより、開発プロセスが合理化され、クライアントとサーバーの実装全体の一貫性が確保されます。
サポートされている言語:
- 。網
- JavaScript
主な機能:
- 標準ランタイムインターフェイス:標準エミッターは、最初にランタイムインターフェイスを生成することに重点を置き、さまざまなランタイムスタックとの柔軟性と容易な統合を保証します。
- カスタム コード拡張: TypeSpec エミッターは、カスタム コードの拡張性を提供し、開発者は生成されたコードを特定のニーズに合わせて調整し、さまざまな環境に適応できるようにします。
- 包括的なコード生成: TypeSpec は、さまざまなプロトコルや資産の種類を含む、クライアントからサーバーまで、開発スタック全体にわたるコード生成をサポートし、統合された開発アプローチを保証します。
TypeSpec のサービス側コード生成機能を使用することで、開発者は手動コーディングを減らし、一貫性を向上させ、全体的な生産性を向上させることができます。
業界ツールチェーンとの相互運用性
TypeSpec は、既存の業界ツールチェーンとシームレスに統合され、相互運用性を確保し、生産性を向上します。 TypeSpec 定義から OpenAPI 仕様を生成することで、開発者は、API ドキュメント用の Swagger、API テスト用の Postman、API をデプロイするための Azure API Management など、OpenAPI 用に設計されたツールの膨大なエコシステムを使用できます。 これには、API ゲートウェイの構成、クライアントとサーバーのコードの生成、API データの検証が含まれます。 この互換性により、チームは現在のワークフローを維持しながら、TypeSpec が提供する構造化された一貫性のある API 設計の恩恵を受けることができます。
優れた開発者エクスペリエンス
開発者の統合には、 Visual Studio Code 拡張機能 と Visual Studio が含まれます。 これらの統合により、オートコンプリート、構文の強調表示、ビルド時のエラー識別、シンボルの名前変更、ドキュメントの書式設定などの機能を使用して、効率的でエラーのないコーディングが提供されます。 たとえば、Visual Studio Code で TypeSpec 定義を記述する場合、拡張機能ではリアルタイムのオートコンプリートと構文の強調表示が提供されるため、正しく一貫性のある API 定義を簡単に記述できます。
さらに、 TypeSpec Playground は、開発者が TypeSpec 構文と機能をリアルタイムで試すことができる対話型環境を提供します。 この Web ベースのツールは、すぐにフィードバックと検証を行い、TypeSpec の学習と導入を容易にします。 TypeSpec Playground によって提供される対話型の実践的なエクスペリエンスにより、開発者の理解と能力が深まり、最終的に、より一貫性のある高品質の API 設計が実現されます。 これらのツールは、開発プロセスを合理化し、エラーの可能性を減らし、新しいチーム メンバーの学習曲線を加速することで、開発者エクスペリエンスをまとめて向上させます。
OpenApiMigration ツールは、既存の API から移行する開発者をさらにサポートするために、OpenAPI 仕様を TypeSpec 定義に効率的に変換する方法を提供します。 この移行ツールは、既存の API ドキュメントの整合性を維持しながら、TypeSpec の導入を簡素化し、高速化します。 3 つの移行例を次に示します。
実際の用途
TypeSpec は、API の設計と開発を効率化するために、さまざまな業界で正常に使用されています。 次に例をいくつか示します。
- Eコマース: オンライン小売プラットフォームでは、TypeSpec を使用して API の設計と文書化を行い、サード パーティのサービスとのシームレスな統合を可能にし、全体的な開発者エクスペリエンスを向上させます。
- 財務: 金融サービス会社は、API 全体の一貫性とコンプライアンスを確保するために TypeSpec を採用し、API ガバナンスに必要な時間と労力を削減しました。
- 医療: 医療プロバイダーは、TypeSpec を使用して患者データ管理用の API を設計し、システム全体のデータの一貫性とセキュリティを確保しました。
始めましょう
オープン ソースのサポート
- プロジェクトの改善に役立つアイデア、フィードバック、投稿を評価し、推奨します。
- 投稿方法の詳細については、 共同作成者ガイドを参照してください。
- 質問がある場合やサポートが必要な場合は、 コミュニティに質問 するか、 GitHub で問題を送信してください。
詳細情報
TypeSpec の詳細については、次の YouTube ビデオをお楽しみください。
- TypeSpec を使用した大規模な API
- TypeSpec を使用したスキーマ優先の API 設計
- TypeSpec 101
- Open Finance Standards に TypeSpec を使用する