Open API 3.0の定義からgolangのサーバコードのスケルトンを作成する
TL; DR
- API定義をSwagger Editorで作成する（Open API 3.0）
- API定義からGolangのサーバコードのスケルトンを作成する
- コードを実装し展開する
注意
初心者のメモです。まだ途中までしか作成してません
API定義をSwagger Editorで作成する（Open API 3.0）
みんなSwaggerなるものを使っている。
仕様ドキュメントと実装が違うなどということはソフトウェア開発ではたびたび経験しているから、ぜひとも避けたい。
聞くに、Swagger Editor というヴィジュアライズしてくれる便利なものもあるらしく、これは便利である
作成した定義は、[File] > [Save as YAML] で ダウンロードできる。
どうもSwaggerがデファクトらしいが、標準化されたOpen APIという書き方があるのなら、個人的にはデファクトといえどそちらに合わせたほうがよさそうに思う。
API定義からGolangのサーバコードのスケルトンを作成する
これをやりたかった。なんでGolangかといえば、あとでコンテナ化してデプロイするときに楽そうだからである。そして、数年前からサーバサイドといえばGolangを使うのがよさげらしいので。
さて、スケルトンコードを作成するには、openapi-generator を使う。
jarファイルをダウンロードして、適当なところに置けばよろしいらしい。
2 - Getting Started
ちなみに、Node JSのラッパーもあるらしく、フロントエンドはNode JSの力を借りるのだから、npm コマンドでインストールした。
npm install @openapitools/openapi-generator-cli -g
openapi-generator version
スケルトンコードを作成するときに、ついでにGolangのプロジェクトを作成してしまう。
Golangはインストールしておく。C:\goなりC:\Users\foo\goとか
ちなみに、Golangのプロジェクトのディレクトリ構成は、検索すると諸説あるように見えるが、そんなことはない。
プログラミングに関して検索するときは、Google検索で１年以内を指定するようにしたほうが良い。
2020/07の現時点では、ここに従うのがよいように思われる
# ここで作成
openapi-generator generate -g go-server -i api\openapi.yaml -o myproject
上のコマンドを実行すれば、myprojectディレクトリ以下ですぐさまGoの開発に入れる。
が、オプションなしのデフォルトで作成したスケルトンコードでは、go-lintの命名規則ルールに引っかかる。
特にVS CodeでGolang拡張機能を使うのであれば、デフォルトのlintツールはgo-lintであるからとてもめんどくさい。
type ServiceOperationsApiController should be ServiceOperationsAPIControllergo-lint
このApiという文字列は、どうやらopenapi-generatorがデフォルトでつける他スケルトンと共通のプレフィックスらしい。
openapi-generator help generate
～ 省略 ～
--api-name-suffix <api name suffix>
Suffix that will be appended to all API names ('tags'). Default:
Api. e.g. Pet => PetApi. Note: Only ruby, python, jaxrs generators
suppport this feature at the moment.
# ここで作成
openapi-generator generate -g go-server -i api\openapi.yaml -o myproject --api-name-suffix API