openapi-generator-cli とは？
openapi-generator-cliは、OpenAPIで書かれた仕様書からコードを生成するものです。
特にGo言語用というわけではなく、WebApplicationFrameworkに従ったコードも生成してくれます。どんな言語、Frameworkに対応しているかは、READMEのOverviewを見てみると良いでしょう。Perlもありますね(ないと思ってた)。
今回、WebApplicationFrameworkにFiberを使ったのですが、残念ながら、Fiberには対応していません。ですが、生成したコードを使うことは出来ます。
openapi-cli-generatorを動かす
今回は、Dockerで動かしました。openapi-generator-cliのオプションとしては、generateから後ろですが、オプションが多いですね。
docker run --rm -u "${UID}:${GID}" -v "${PWD}:/local" \
openapitools/openapi-generator-cli generate -g go \
--skip-validate-spec \
--global-property models,supportingFiles,modelDocs \
--additional-properties withGoMod=false \
--package-name package名 \
-i /local/docs/openapi/openapi.json \
-o /local/internal/interfaces/api/generated/package名/
一つずつ見ていきましょう。
-
generate... コードを生成する。そのままです。以下は generateのオプションです -
-g go... Go用のコードを生成する -
--skip-validate-spec... 仕様書の書式のチェックをスキップ -
--global-property models,supportingFiles,modelDocs... models,supportingFiles,modelDocsを生成する -
--additional-properties withGoMod=false... go.mod を作らない -
--package-name package名... package名を指定する -
-i /local/docs/openapi/openapi.json... 仕様書を指定する -
-o /local/internal/interfaces/api/generated/package名/... 出力先の指定(/localに、current directoryをmountしています)
--global-property を指定しないと、生成したコードをそのまま使えませんでした。今回使用する用途的に必要そうな最低限の組み合わせになります(modelDocsは別に不要ですが)。
生成されたコードを使う
openapi-generator-cliが生成するのは、主に、
-
client.go... APIを叩くためのコード -
configuration.go... エンドポイントのURL等の設定っぽい -
model_*パス_request.go... 各APIのリクエストに関する型や実装 -
model_*パス_response.go... 各APIのレスポンスに関する型や実装
GET
で使え...ません。GETのAPIに関しては、model_*パス*request.goが存在しないので、fiberのQueryParserに渡せません。
--global-property に apis を渡せば、api_*.goにGETようの型は作ってくれるのですが、構造体のメンバがprivateなので、FiberのQueryParserに渡すことができません。残念。
コードを参考にして、構造体を作れば楽なのは楽かもしれません。
POST
model_*パス*request.goの中にJSON用の構造体が入っていますので、それが使えます。例えば、こんな感じですね。
type YourApiRequest struct {
UserID string `json:"user_id"`
}
fiberのBodyParserにそのまま渡すことが出来ます。
c.BodyParser(req)
レスポンス
model_*パス*response.goの中にJSON用の構造体が入っていますので、それが使えます。例えば、こんな感じですね。
type YourApiNameGet200Response struct {
Result []YourApiNameGet200ResponseResultInner `json:"result"`
}
この型通りにデータを作ってやって、JSONにすれば、そのままレスポンスに使えます。
data := YourApiNameGet200ResponseResultInner{
// 略
}
c.JSON(your_pacakge.NewYourApiResponse(data))
各POSTの型にダミーのメソッドを作る
codegen/openapi-request-generator.sh というプログラムで、CanWrapというメソッドを各作ります。やってることは、以下のように超単純です。
#!/bin/bash
dirs=$1
if [ "$dirs" = "" ]; then
dirs="your_pacakge_name"
fi
for dir in $dirs; do
echo -e "package $dir\n" > internal/interfaces/api/generated/$dir/generated_func.go;
grep 'Request struct' -r internal/interfaces/api/generated/$dir | grep type |cut -d ' ' -f 2 | sort | xargs -I {} echo "func (*{}) CanWrap() { }" >> internal/interfaces/api/generated/$dir/generated_func.go
go fmt internal/interfaces/api/generated/$dir/generated_func.go
done
各Postリクエストの型に対して、CanWrapという何もしないメソッドを定義しています。CanWrap()は、RequestWrapper interfaceを満たすためのメソッドです。
type RequestWrapper interface {
CanWrap()
}
これで何が嬉しいかと言うと...前回書いたやつが、できるようになりますね。
以下、略。
終わり
以上、openapi-generator-cli を使えば、楽できますよという話でした。