見出し画像
Photo by hanaco_san

Quarkus, microprofile, OpenAPI GeneratorでJava WebAPIクライアントを作る

tkhm

OpenAPI Generatorのmicroprofileのライセンスの問題は、Issueを起票してからわずか数時間しない内に修正されて、最新のmasterに入った。
Core Maintainerなのは知っていたから早いかもとは思っていたけど、こういう対応を受けると、批判的な立場をとる人も一気にファンになるよなあと思って感心したし、なによりありがたかった。

というわけで、前回同様、次のようなConfigを読み込む。

openapi-config.json: 

{
   "apiPackage": "myapp.resources.resources",
   "dateLibrary": "java8",
   "generatePom": false,
   "library": "microprofile",
   "modelPackage": "myapp.model",
   "openApiNullable": true,
   "packagesName": "myapp",
   "sourceFolder": "java"
}

そんでAPI定義ファイルを読み込ますと......まさに求めていたものが。

microprofileなので、APIのエンドポイントとその応答だけが定義されているInterface、そして、それが返す用のモデルクラス、あとはAPIとの応答の際の失敗を処理するApiException.javaとApiExceptionMapper.javaが生成される。

そして呼び出すときには、クラス内にこんな感じで仕込む。

   @Inject
   @RestClient
   FoodsApi foodsApi;
   @Override
   public FoodModel fetchAllFoods() {
       try {
           List<Food> foodList = foodsApi.getFoods();
           System.out.println(foodList.size());
       } catch (ProcessingException | ApiException e) {
           // TODO Auto-generated catch block
           e.printStackTrace();
       }
   }

あとは、実際にアクセスするそのアクセス先を解決してあげるためにapplication.propertiesに、Interfaceへのパスに合わせて次のように定義すればOK。
挙動を確認できていないけど、もしdevとtestとprodのprofileでそれぞれアクセス先が変わる、とかがあるなら、他のと同様に頭に%dev.とか付ければいいんだろうと思ってる。

myapp.resources.FoodsApi/mp-rest/url=http://foods.example.com


本当に簡単。OpenAPI Generatorが作ってくれるものも必要最小限だし、それを使って呼び出すコードもmicroprofileのおかげで必要最小限。
こういった仕組みがスキーマ駆動開発を支えてくれているなと強く思う。

Quarkusを使っている場合はこの仕組みを追加するために必要なのは、rest-clientとrest-client-jsonbだけみたい。
build.gradleに直接加えるならこんな感じ。


   implementation 'io.quarkus:quarkus-resteasy'
   implementation 'io.quarkus:quarkus-resteasy-jsonb'


多くの人がOpenAPI Generatorをどういったユースケースで使用しているのか自分は知らないけれど、少なくとも自分としては、スキーマ駆動開発を前提に、OpenAPIの定義ファイルを見て読み書きしなければならないボイラープレートコードの部分を生成させ、それらを元のアプリの仕組みに乗せる、そういうことを期待している。

だから、サーバーサイドのJavaで生成するときは必ず "jaxrs-spec" をGeneratorには指定するし、オプションでも"InterfaceOnly" を有効にしている。

JavaのWeb API内部から別のWeb APIを呼び出すために今回はJavaのクライアントサイドのコード生成をしたけれど、microprofile以外は何かと生成されるコードが多くて戸惑いが多かった。microprofileなら仕組みさえわかればすごく使いやすいので、当面仕事でも周りには推進していきたい。

想像するに、microprofileにすると、実際のWeb APIを呼び出す処理が隠されるので、そのデバッグが辛くなるとか、理解が追いつかないとか、そういう課題はあるのかも。

ちなみに、動かすまでにはこの辺を確認した。

OpenAPI Generator側では多彩なオプションが用意されているけれど、可能だったら簡単にそれぞれの特徴についても言及してもらえると嬉しい......けど、OpenなIssueの数もPRの数も結構凄まじいから現状は厳しいか。自分も時間を見つけて受けている恩を返す意味でContributionすることも検討、してみようかな。

王道のSpringよりもQuarkusがとても好きなので、Javaで、特にWeb APIを作っている人にはどんどんとQuarkusの良さを伝えていきたいなあ。
少し長くなったけれど今日はそんなところ。

posted here: https://blog.tkhm.dev/2020/10/quarkus-microprofile-openapi.html