🍳

API Gateway(Google Cloud)に適用するOpenAPIドキュメントをチェックするGitHub Actions

いばらき

2023/01/22に公開

はじめに

GCPのAPI Gatewayは、APIの定義を記載したOpenAPIドキュメント(v2.0)を渡すことで、設定できます。
しかし使ったことがある人なら分かると思うのですが、めちゃくちゃエラーが出ます。通常のviewerで問題なく表示できるドキュメントを使っても大量のエラーを吐くことがよくあります。しかも、何故か今どきv2しか受け付けません。v3で書くともちろんエラーを吐きます。

APIを修正してプルリク出してレビューしてマージして適用しようとすると、適用失敗してエラーになり作り直しになることが容易に想像ができます。これはツライです。

ツライので、プルリク時にエラーチェックをするGitHub Actionsを書きました。

処理概要

エラーチェックをすると書きましたが、もちろんGCPにOpenAPIドキュメントをエラーチェックをする気の利いたAPIは存在しません。（私は見つけられませんでした。ないですよね？）

では、どうするかです。

まずは、公式ドキュメントを参照して、API GatewayにOpenAPIドキュメントを適用する処理を見ていきましょう。

API Gateway作成済の状態から、新規のOpenAPIドキュメントを元にAPI Gatewayを更新するフローを考えます。すると、下記の2段階で実行できることが分かります。

OpenAPIから新しいconfigを作成する

gcloud api-gateway api-configs create ${{コンフィグID}} --api=${{API ID}} --openapi-spec=${{OpenAPIドキュメントのファイルパス}} --project=${{プロジェクトID}}

作成したconfigをAPI Gatewayに適用する

gcloud api-gateway gateways update ${{APIゲートウェイ ID}} --api=${{API ID}} --api-config=${{コンフィグID}} --location asia-northeast1 --project=${{プロジェクトID}}

はい。もうおわかりですね。
1でconfigを作成する時点でOpenAPIを読み込んでいますので、エラーは1で発生します。
そして1を実行した時点だと、既存のAPI Gatewayには影響はありません。
つまりプルリク時に1が成功するかを確認して、2は実行しなければよいのです。

しかし、プルリクの度にconfigが作成されますので、ゴミが増えていきます。
作成に成功したら即座に削除しましょう。

gcloud api-gateway api-configs delete ${{コンフィグID}} --api=${{API ID}} -q --project=${{プロジェクトID}}

GitHub Actionsを書こう

前提として

Github Actions内でGcloud CLIを使う為には認証が必要です。今回はOIDCで認証しています。やり方は本題から外れるのでこの記事では説明しません。
設定方法を知りたい方は、例えば下記の記事などを参照していただければと思います。

書いたyaml

こちらが、実際に書いたプルリク時のGithub Actionsのyamlです。

ついでにマージされたら自動で適用する方も書きました。

少しだけ補足

varsについて

変数は基本的にvarsから取ってくるようにしました。
見慣れないかもしれないですが、2023/01/10のupdateで外部から変数を設定できるようになったので早速使いました。

参照

Open APIの定義ファイルへのパスが変数に出していない件

Open APIのパスもプロジェクトによって違うと思うので変数にしたかったのですが、on:pull_requestのpathsにも指定したかったため直書きにしています。Actionsの起動条件に変数を使うと動かないんですよね。。。いい感じに外部から投入する方法ないですかね。。。

設定名(Config名)について

雑な重複回避でConfig名には日時付与するようにしました。それはよいのですが、変数を使うにあたりset-outputが今年の6月から使えなくなるので$GITHUB_OUTPUTを使っています。

参考

その他、無駄に詰まった点

テスト環境を用意して動作確認をしていたのですが、テスト環境でのGoogle CloudのAPI有効化が不十分で動かなくて苦戦しました。
具体的には、下記の2つが足りてませんでした。

IAM Service Account Credentials API
Compute Engine API

特にCompute Engine。普通にプロジェクト作ったら最初の方に有効化するので完全に盲点でした。というか、なぜCLIからAPI Gatewayの設定するのにCompute Engineが必要なのでしょうか。コンソールから操作する場合は不要なのに。
エラーも下記のようにサービスアカウントが無いと言われるので「そうだねそんなアカウントないよね」って感じで、解決方法が分かりにくかったです。

(gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION: Service account "projects/-/serviceAccounts/(プロジェクト番号)-compute@developer.gserviceaccount.com" not found. Try specifying a service account that exists in this project.

どの操作にどのAPIが必須なのかが簡単に分かる手段あるのでしょうか?
GPCに詳しい人教えてください。

最後に

GCPのAPI GatewayはOpen APIのドキュメントで定義することで、強制的にコード化できるしAPI設計書も同時に書けるという点では良いのですが、

直感的でないので、分かりにくいし、ハードルが高い
Open APIのバージョンが古く、レガシーな書き方が強要されるのがツライ

といったあたりが使いづらいと感じます。
アップデートして改善してほしい。

NCDCエンジニアブログ

NCDC株式会社( ncdc.co.jp/ )のエンジニアチームです。募集中のエンジニアのポジションや、採用している技術スタックの紹介などはこちら( github.com/ncdcdev/recruitment )をご覧ください！ ※エンジニア以外も記事を投稿することがあります