SpringBoot×OpenAPI入門 〜Generation gapパターンで作るOpenAPI〜

背景

Javaのコミュニティイベント「JJUG CCC 2019 Fall」に参加。
そこで聞いた「Swagger ではない OpenAPI Specification 3.0 による API サーバー開発」の登壇内容に触発されて超簡単なOpenAPIを作った話。（浅いです）

今回のゴール

SpringBootを使ってOpenAPIを書く

OpenAPIを使った開発フロー(ざっくり）

ルール：Generation gapパターン　→　自動生成したクラスファイルは編集しない。

1. API定義ファイルを用意

OAS（OpenAPISpecification）にあるサンプルを使用

2. 定義よりコード自動生成

Gradleのプラグイン【openapi-generator-gradle-plugin】を使用。
APIの定義ファイルよりコードを自動生成してくれるGradleプラグイン。

build.gradle

plugins {
    id "org.openapi.generator" version "4.2.1"
}

ポイント１：コンパイル時の設定

自動生成したクラスファイルをコンパイル時に含めるように設定

build.gradle

compileJava.dependsOn tasks.openApiGenerate
sourceSets.main.java.srcDir "${openApiGenerate.outputDir.get()}/src/main/java"
sourceSets.main.resources.srcDir 

ポイント２：OpenapiGeneratorの設定

openapi-generator-gradle-pluginの実行例をほぼほぼコピーでOK。
ただ、インターフェイスを作成するようにコンフィグファイルを操作。

build.gradle

//https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-gradle-plugin

openApiGenerate {
    generatorName = "spring"
    //コンフィグ設定
    configFile = "$rootDir/specs/config.json".toString()
    //サンプルAPI指定
    inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString()
    outputDir = "$buildDir/generated".toString()
    apiPackage = "org.openapi.example.api"
    invokerPackage = "org.openapi.example.invoker"
    modelPackage = "org.openapi.example.model"
    configOptions = [
        dateLibrary: "java8"
    ]
    systemProperties = [
        modelDocs: 'false'
    ]
}

config.json

{
  "interfaceOnly": true
}

クラスの自動生成はGradleのタスク【openApiGenerate】でOK。

タスク実行すると、以下のJavaファイルが自動生成される

3. API実装

自動生成されたインターフェイスからimplementして、コントローラーを生成

PetsApiController.java

@RestController
public class PetsApiController implements PetsApi{
    @Override
    public ResponseEntity<List<Pet>> listPets(@Valid Integer limit) {
        System.out.println("Here list pet");
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

完成！！

完成したコード

おまけ:OpenAPIのドキュメントツールを使ってみた

OpenAPIのドキュメントツール（redoc）を使って、ドキュメントを自動生成。
※　前提：Dockerが入っていること

docker run -it --rm -p 80:80 \
  -v $(pwd)/specs/petstore-v3.0.yaml:/usr/share/nginx/html/swagger.yaml \
  redocly/redoc

出力イメージ：定義ファイルを元にAPIのパラメータや戻り値を見やすい画面で出力

参考資料

Swagger ではない OpenAPI Specification 3.0 による API サーバー開発
https://www.slideshare.net/techblogyahoo/swagger-openapi-specification-30-api