読者です 読者をやめる 読者になる 読者になる

GeekFactory

int128.hatenablog.com

Gradle Swagger Generator Pluginを公開します

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

github.com

もともとは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を利用しています。

活用例

例えば、REST APIサーバを開発するプロジェクトでは以下のような活用例が考えられます。

  • APIサーバのコードを生成し、プロダクトコードから利用する。
  • APIクライアントのコードを生成し、JARをMaven Repositoryに公開する。
  • APIドキュメントを生成し、GitHub PagesやS3 Static Web Hostingで公開する。

リポジトリにはサンプルプロジェクトも置いてあるので、ぜひご活用ください。

github.com