Openapi 3.0 (Swagger)のツール周りの調査結果

やりたいこと

• ファイル分割して書きたい
• 複雑なツールの構成にしたくない

エディタ

好みのエディタ

ローカルだとvalidationがリアルタイムでできなさそうなので、要再調査

他

Openapi Codegeneratorだけで十分のようだ。

Openapi CodegeneratorはDockerでやるのが環境を汚さなくて良さげ
./作業ディレクトリ/src の中にyamlを書いていく前提
dockerさえ入っていて、起動していればイメージはオンライン上にあるので、下記コマンドでいけるはずである。

Validator

openapi-codegeneratorのvalidate機能

docker run --rm -v ${PWD}:/work --workdir=/work openapitools/openapi-generator-cli validate -i src/index.yaml

コード連結

openapi-codegeneratorのなぜかDocumentってリストの中にあるopenapiとopenapi-yamlテンプレートを使う。

json

docker run --rm -v ${PWD}:/work --workdir=/work openapitools/openapi-generator-cli generate \
    -i src/index.yaml \
    -g openapi \
    -o /work/oepnapi-json

yaml

docker run --rm -v ${PWD}:/work --workdir=/work openapitools/openapi-generator-cli generate \
    -i src/index.yaml \
    -g openapi-yaml \
    -o /work/oepnapi-yaml

ドキュメント

openapi-codegeneratorのドキュメント生成generatorを使えば良い
ドキュメントのリストの中にopenapiとopenapi-yamlというテンプレートもあるがコイツラは実は人間飲みやすいドキュメントではなく、コード連結してくれるやつである。
html2が自分にはしっくり来たかな。
htmlは文字化けした。日本語には向かなそうである。

- cwiki
- dynamic-html
- html
- html2

サンプルコード

docker run --rm -v ${PWD}:/work --workdir=/work openapitools/openapi-generator-cli generate \
    -i src/index.yaml \
    -g html2 \
    -o /work/doc

モックサーバ

• openapi-codegeneratorのgenerate機能がよい。go-serverにすれば後で配布も楽そう。
• api-sproutというツールを使おうとしたが分割ファイルに対応していないようだ。

docker run --rm -v ${PWD}:/output --workdir=/output openapitools/openapi-generator-cli generate \
    -i src/index.yaml \
    -g go-server \
    -o /output/go-mock-server

立ち上げるためには依存ライブラリがあったので下記のようにしたらできた。

cd go-mock-server
go get -d -v ./...
go run main.go

クライアント生成

Flow対応のJS版とTypescript版にお世話になることが多そうだ。

docker run --rm -v ${PWD}:/output --workdir=/output openapitools/openapi-generator-cli generate \
    -i src/index.yaml \
    -g  typescript-fetch \
    -o /output/api-client-typescript