はじめに
OpenAPIとは、「YAML形式」か「JSON形式」で記載するAPI仕様書の記述フォーマットです。
今回はメンテナンス性が高いOpenAPIの定義ファイル分割をメインに以下について説明していきます。
サンプルコード
OpenAPIとは
OpenAPIとは、「YAML形式」か「JSON形式」で記載するAPI仕様書の記述フォーマットです。元々はSwaggerとして知られていました。
このフォーマットを利用することで以下のAPI構造を記述でき、設計・開発・テストおよびドキュメント作成のプロセスを簡素化・標準化するのに役立ちます。
- APIのエンドポイント
- リクエストとレスポンスの形式
- 認証方法
- etc...
以下の記事が分かりやすく解説してるので、この記事では詳細は割愛します。
OpenAPIの定義ファイル分割
定義ファイルを1つのファイルで管理した場合、長すぎる1つのファイルになるため保守が大変です。特にサンプルデータも記載すると大変長いファイルになります。
そのため、定義ファイルを分割することで管理を楽にします。フォルダ構成は以下になります。
docker
└ api-mock
├ openapi.yaml # マージ後のAPI仕様書
├ base.yaml # マージ前のAPI仕様書
├ examples # レスポンス例
├ paths # エンドポイント
└ schemas # スキーマ
分割したままだと使えないので、コマンドを実行して分割された定義を1つにマージします。
※ 今回はswagger-mergerというライブラリを使ってマージします。
分割されているファイルが別のファイルを参照していると、1度の実行ではすべてマージされません。そこで、スクリプトを組んでファイル参照がなくなるまでマージ用のコマンドを実行してマージします。
作成したスクリプトは以下になります。
#!/bin/sh
# マージ前後のファイルを指定
base_filename="docker/api-mock/base.yaml"
out_filename="docker/api-mock/openapi.yaml"
# 一回目のマージ
yarn swagger-merger -i $base_filename -o $out_filename
# 参照ファイルがなくなるまでループする
# ※ "$ref: [^']*\.yaml"が一致する文字列がなくなるまでループする
while grep -q "\$ref: [^']*\.yaml" "$out_filename"
do
yarn swagger-merger -i $out_filename -o $out_filename
done
echo "出力が完了しました"
| マージイメージ |
|---|
 |
クライアントコードの自動生成
OpenAPIを使っているので、クライアントコードを自動生成して開発効率を向上します。
以下のサンプルではtypescript-axiosのジェネレータを使っています。
yarn openapi-generator-cli generate \
-i "定義ファイルの場所" \
-o "出力先" \
-g typescript-axios
おわりに
今回はOpenAPIに関して以下について説明しました。
OpenAPIの定義ファイルを分割することでメンテナンス性を担保できます。
さらにOpenAPI Generatorを使うことで型安全なフロントエンドを開発しやすくなります。
参考
Discussion