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 コマンドでインストールした。

openapi-generatorのインストール

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であるからとてもめんどくさい。

Apiが大文字じゃない！と文句を言う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