見出し画像

TypeSpecについて簡単にまとめてみた

ぐんこあ@ソフトウェアエンジニア(仮)

先日参加したLT会でTypeSpecというツールを初めて知りました。

後で自分自身が見返せるように、ざっくりとしたメモ感覚でまとめてみました！


1.TypeSpecとは？

TypeSpecは、APIの設計とドキュメント化を簡単にするためのツールです。TypeSpecを使うことで、APIのエンドポイント、リクエスト・レスポンスのデータ構造、認証方法などを、TypeSpec独自のDSL（ドメイン固有言語）で明確に定義できます。APIを設計し、それを様々なプログラミング言語で利用できる形に自動生成する際に使われます。

DSLとは？

DSL（ドメイン固有言語）というのは、特定の目的に特化した専用の言語のことです。

TypeSpecのDSLとは？

TypeSpecのDSLは、APIを設計するためだけに作られた特別な言語で、この言語を使うと、APIの仕様を簡単に書けるようになります。これは、プログラミング言語のように複雑なコードを書く必要がなく、APIの仕様を簡潔に表現できるからです。



2.TypeSpecの役割

一貫性

TypeSpecを使うと、APIの設計を統一した方法で書けます。これにより、APIを使う人が使い方を理解しやすくなります。

自動生成

APIの仕様を元に、プログラミング言語（例えば、TypeScriptやDart）のコードを自動的に生成できます。手動でコードを書く手間が省け、ミスも減ります。

ドキュメント

TypeSpecは、APIの使用方法を説明するドキュメントも自動で作成します。これにより、他の開発者がAPIを簡単に使えるようになります。

具体例　ペットストアAPIを定義する

このAPIでは、
ペットの一覧を取得する (GET /pets)
ペットを注文する (POST /orders)
という２つの機能があります。

TypeSpecを使うと、これらの機能をTypeSpecのDSLで分かりやすく記述できます。しかも、この定義ファイルから、実際にAPIを動かすための コード や、APIの使い方を説明する ドキュメント を自動生成できます。

openapi: 3.0.0
info:
title: ペットストアAPI
version: 1.0.0
paths:
/pets:
get:
summary: ペット一覧を取得
responses:
'200':
description: ペット一覧
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
/orders:
post:
summary: ペットを注文
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
responses:
'201':
description: 注文成功
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
name:
type: string
breed:
type: string
OrderRequest:
type: object
properties:
petId:
type: integer
quantity:
type: integer

この定義ファイルでは、以下を定義しています。

  • openapi: OASのバージョン

  • info: APIのタイトルとバージョン

  • paths: 各エンドポイントの定義

    • /pets: ペット一覧取得API

    • /orders: ペット注文API

  • components.schemas: データ構造の定義

    • Pet: ペットの情報

    • OrderRequest: 注文情報


コードとドキュメントの生成

TypeSpecで定義ファイルを記述したら、TypeSpecのCLIツールを使って、APIサーバーのコードやAPIドキュメントを自動生成できます。

例えば、Node.jsとExpressを使ってAPIサーバーのコードを生成する場合、以下のようなコマンドを実行します。

typespec compile petstore.tsp -o ./petstore-server

※どの方法を選択するかは、プロジェクトの要件、使用言語、フレームワーク、開発チームのスキルセットなどを考慮する必要がある。

これにより、./petstore-serverディレクトリに、APIサーバーのコードが生成されます。生成されたコードは、定義ファイルに基づいて、適切なルーティング、リクエストバリデーション、レスポンスフォーマットなどが実装されています。


3.どのような状況で役立つか

複数のクライアント向けにAPIを提供する場合

APIを一度設計すれば、TypeSpecを使って異なるプログラミング言語（例えばTypeScriptやDart）のクライアントコードを自動生成できます。これにより、フロントエンドやモバイルアプリなど、様々なクライアントが同じAPIを利用できるようになります 。

一貫したAPIドキュメントが必要な場合

APIを設計するとき、ドキュメントを手作業で書くのは大変です。TypeSpecを使うと、APIの仕様から自動でドキュメントを生成できます。これにより、最新のドキュメントを維持しやすくなり、他の開発者がAPIを理解しやすくなります

開発速度を向上させたい場合

APIの設計からコード生成までを自動化することで、手動でコードを書いたり修正したりする時間を大幅に削減できます。これにより、開発チームの効率が向上し、より早くプロジェクトを進めることができます 。

4.TypeSpecのメリット

TypeSpecを使うメリットを簡潔にまとめると、以下の通りです。

一貫性のあるAPI設計

TypeSpecを使うと、APIの仕様を統一されたフォーマットで記述できます。これにより、チーム全体で一貫した設計ができ、保守性が向上します

自動コード生成

APIの仕様からTypeScriptやDartなどのクライアントコードを自動で生成できます。これにより、手動でコードを書く時間を節約し、ヒューマンエラーを減らせます。

自動ドキュメント生成

APIの仕様からドキュメントを自動生成できるため、最新のドキュメントを維持しやすく、開発者がAPIを理解しやすくなります。

効率的な開発

設計、コード生成、ドキュメント化を自動化することで、開発プロセス全体を効率化し、迅速にプロジェクトを進められます

マルチプラットフォーム対応

TypeSpecを使うと、同じAPIをいろんなプログラミング言語やデバイスで使えるようにできます。例えば、ウェブアプリでもモバイルアプリでも、同じAPIを使ってデータをやり取りできるので、一貫性を保てます。これにより、フロントエンドとバックエンドの連携がスムーズになります。



まとめ

これらのメリットにより、TypeSpecはAPI開発において非常に強力なツールとなります。

TypeSpecを使うと、APIの仕様を統一された書き方で定義できるため、開発者全員が同じスタイルとルールに従ってAPIを設計・実装することができます。これにより、開発の効率が向上し、エラーを減らすことができます。



感想

理解をしようと、AIを使って解説を読みながら記事を作りましたが、まだTypeSpecを活用をしていないので良さがまだ実感できず笑

TypeSpecはどのようなツールなのかを知ることができたので、実践してみてまた記事にしていこうと思います！




いいなと思ったら応援しよう！