【エンジニアブログ】TypeSpecを使ったOpenAPIドキュメント生成

GMOメイクショップコアグループの原田です。フロントエンドとバックエンド間のREST APIやり取りに型定義が無いという課題があったため、OpenAPIドキュメントを作成、それを元にした型定義をフロントエンドで利用できるようにしました。今回は、OpenAPIドキュメントを書くために利用したTypeSpecをご紹介します。

• 課題
• 解決策
• TypeSpecとは?
• • TypeSpecの記法
  • モデル定義
  • エイリアス
  • スカラー
  • 定数定義
  • ルーティングデコレーター
  • ジェネリクス
• TypeSpecのコンパイル方法
• TypeSpecのコンパイル結果
• 利用してみた感想
• まとめ
• 参考資料

課題

次世代EC管理画面ではSPAを採用しており、バックエンドとのやり取りが頻繁に発生します。やり取り方法にGraphQLを使うエンドポイントは graphql-codegenを用いた型定義が存在しますが、REST APIへのリクエストには型定義が無く、anyになっている状況がありました。しかし、型定義が無いとなると、正確に何をやり取りしているかがわからず、改修やリファクタに不安が生まれて時間がかかってしまいます。今回はこの問題の解消に取り組みました。

解決策

同一のモノレポ内の別プロジェクトでOpenAPIを用いたAPIドキュメントが利用している点から、まずOpenAPIを使うのが今後のメンテナンス性向上のためにベストな選択だと判断しました。また、OpenAPI Generator TypeScript Axiosで型付きリクエストの自動生成 | Offers Tech Blogという記事の事例を読み、OpenAPIドキュメントとそれを元に生成した型定義を使う方法を採用することとしました。しかしながら、対応するエンドポイント数が多く、OpenAPIドキュメントを手書きするのは時間がかかりそうです。そこで、今回はAPIドキュメントを簡潔に書けるというTypeSpecの検証を行いました。

TypeSpecとは?

TypeSpecは、API ドキュメントを記述するための言語です。TypeScriptに似た構文を持ち、OpenAPI v3形式に簡単にコンパイルできるのが特徴です。TypeSpecでは、ジェネリクスやimportを利用できるため、API仕様の記述を簡潔に保ちながら、大規模なドキュメント生成が可能です。

github.com

TypeSpecの記法

TypeSpecの記法は、TypeScriptでのフロントエンド経験がある開発者にとっては、とてもわかりやすい構文になっています。 以下に構文の例を紹介します。

モデル定義

リクエストやレスポンス等の構造を定義するためにはmodelキーワードを使用します。モデルはOpenAPIの出力時にコンポーネントスキーマとして出力されます。

https://typespec.io/docs/language-basics/models

エイリアス

型の別名を定義するのには、エイリアス構文を利用します。 エイリアスはドキュメント作成時の文法エラーを防いだり、バリデーションを出力するために利用できます。

https://typespec.io/docs/language-basics/aliases

スカラー

型に対する制約（例: 数値の範囲）を持つカスタム型を定義する際にはスカラーを利用します。 スカラーはモデルと同様にOpenAPIの出力時にコンポーネントスキーマとして出力されます。

https://typespec.io/docs/language-basics/scalars

定数定義

定数一覧を定義できるenumもあります。定数はリクエストのバリデーションとして出力されます。 便利ですが、enumへのコメントはOpenAPIのドキュメント仕様では表現できずビルド時に失われてしまうため注意が必要です。

https://typespec.io/docs/language-basics/enums

ルーティングデコレーター

APIエンドポイントを定義するためには interfaceを書き、その中に@route や @post等のデコレーターを使用して記述します。 OpenAPI特有のドキュメント情報も同様にデコレーターを使い記述することができます。

ジェネリクス

ジェネリクスの機能は、ほとんどTypeScriptと同様の書き方で利用できます。 TypeSpecでの数値はnumber型ではなくnumeric型と記載する点に注意が必要です。

TypeSpecのコンパイル方法

TypeSpecで記述したドキュメントは、Node.jsのTypeSpecコンパイラを使ってコンパイルします。 例として、任意のプロジェクトフォルダで下記ファイルを作成してコンパイルすると、distフォルダ内にopenapi.yamlが生成されます。

TypeSpecのコンパイル結果

上記の例では、下記のようなOpenAPIスキーマが生成されます。

出力したものを、Swaggerや Redoclyを使い読み込み/書き出しするとAPIドキュメントを確認できます🎉

利用してみた感想

文法を覚えるのにやや慣れが必要ですが、JSONを直接書くよりは、確かに簡単に書くことができました。 リポジトリのREADMEで紹介されていたVSCode拡張機能も正しく動作し、書き心地がとてもよかったです。TypeScriptを使い慣れた方にはぜひおすすめしたい言語だと感じました。 一方で、TypeSpecではOpenAPIで表現できない情報まで記載できてしまい、OpenAPIへの出力時に何が保持され、何が失われるかわかりづらい点は少し懸念でした。

まとめ

この記事では TypeSpecを使いドキュメントを作成し、OpenAPIドキュメントをコンパイルする方法を紹介しました。 次回は、生成したOpenAPIドキュメントを活用して、フロントエンド側で型安全なAPI通信を実現した方法を紹介します。

参考資料

• https://typespec.io/docs/
• TypeScript のような構文で OpenAPI のスキーマを定義する TypeSpec
• OpenAPIのスキーマ定義を、プログラム的に書けるTypeSpecを使ってみた #swagger - Qiita
• TypeSpec が OpenAPI や JSON Schema を書くのに良かったので紹介する
• • GitHub - d-kimuson/switchbot-api-openapi: OpenAPI Schema for Switchbot API

◆　他のBlogはこちらから⇒ https://tech.makeshop.co.jp/◆

最後までお読みいただきましてありがとうございました。ご応募お待ちしています！