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