gradle-swagger-generator-pluginにOpenAPI Generator対応のPRがマージされた

OpenAPI / Swagger関連の勉強をしていて、gradle-swagger-generator-pluginを見つけました。

gradle-swagger-generator-pluginはOpenAPI文書から、Swagger UI, ReDocなどのHTMLやコード生成を行ってくれます。

コード生成の有名どころだとswagger-code-genとopenapi-generatorが、OpenAPI文書からコード生成をしてくれます。
gradle-swagger-generator-pluginでは、コード生成はバックエンドとして、swagger-code-genのCLIを使用しています。

openapi-generatorはもともとはswagger-code-genからフォークしたものらしいのですが、
機能としてはswagger-code-genにはバリデーションがないけれど、openapi-generatorにはバリデーションがあるという状況で、
gradle-swagger-generator-pluginは独自にJSON Schemaを使用したバリデーションも提供しています。

ただし、OpenAPI 3.0のほうのバリデーションは行ってくれません。これはまだOpenAPI 3.0のスキーマファイルは作業中だからだそうです。


いろいろ試した結果、gradle-swagger-generator-pluginのほうが、DSLが私の好みだったが、バックエンドとしてはopenapi-generatorが使いたいという状況だったので、
コード生成にOpenAPI Generatorを使用する変更を行ってPRしていました。

github.com

無事マージされてよかったです。

下記のような学びがあって、やってよかったなと思います。

  • gradle自体の理解 / これまでも使ってはいましたが、汎用ビルドシステムとしての理解は深まっていませんでした。Project / Task / Artifact / Dependencyなどの概念がだいぶ頭に入ってきました。
  • gradleプラグインの作り方 / Gradleにおけるプラグインとは何か? またGradle Test Kitの存在をしりました。
  • Groovyのテストフレームワーク Spock / パラメータの違うテストを一つにまとめるのは本当に便利でした。やってみると「おなじテストを複数回実行する」から見るSpockのUnrollの世界 - Qiitaがすごく実感できます。
  • OpenAPIの仕様や議論/問題点などの把握 / OpenAPI 3.0はXMLを返すAPIスキーマ(Relax NGXML Scheme)なども実は議論のなかにあるということを知りました。その辺いらないよとは思います。
  • GitHubのPRの実際 / これまでは自身のリポジトリにPRから自己解決マージするみたいのをやっていましたが、初めてPRしたのでやっぱりいろいろ戸惑いました。下記2つの記事は読んでおくべきです。

hnw.hatenablog.com
stackoverflow.com