Gradle Swagger Generator Pluginを公開します

GradleでSwagger YAMLからAPIサーバやAPIクライアント、APIドキュメントを生成するプラグインを作りました。

もともとはGradle Swagger Codegen Pluginという名前でしたが、コードだけでなくドキュメントの生成もできるようになったので名前を変更しました。

コードの自動生成

SpringベースのAPIサーバを生成するビルドスクリプトの例を以下に示します。

plugins {
  id 'org.hidetake.swagger.generator' version '1.4.0'
}

repositories {
  jcenter()
}

dependencies {
  swaggerCodegen 'io.swagger:swagger-codegen-cli:2.2.1'
}

generateSwaggerCode {
  language = 'spring'
  inputFile = file('petstore.yaml')
}

実際は、APIサーバを自動生成するサブプロジェクトを作り、プロダクトコードのプロジェクトから依存関係を設定するとよいでしょう。自動生成コードに手を入れるとAPI仕様の変更を取り込むコストが大幅に高くなるので、サブプロジェクトのビルドでコード生成とコンパイルを行うとよいです。

コード生成にはSwagger Codegen CLIを利用しています。

ドキュメントの自動生成

APIドキュメントを生成するビルドスクリプトの例を示します。

plugins {
  id 'org.hidetake.swagger.generator' version '1.4.0'
  id 'org.asciidoctor.convert' version '1.5.3'
}

repositories {
  jcenter()
}

generateSwaggerDoc {
  inputFile = file('petstore.yaml')
}

参考までに、OpenAPIで公開されているpetstore.yamlから生成したAPIドキュメントを下記に置いています。

https://s3-ap-northeast-1.amazonaws.com/gradle-swagger-generator-plugin/SNAPSHOT/index.html

ドキュメント生成にはSwagger2MarkupとAsciidoctor Gradle Pluginを利用しています。