MicroProfile OpenAPIによるAPI管理（Part1）：既存のJavaコードをドキュメント化する
富士通技術者ブログ～Javaミドルウェア～

はじめに

マイクロサービスを始めたときに出てくる課題の一つに、サービスを追加・修正する度に必要となるAPI管理があります。このシリーズでは2回に分けて、MicroProfile OpenAPIを使ったAPI管理（注1）を紹介します。
なお、ここで紹介するプログラムの完全なソースコードは、以下で参照できます。

• https://github.com/fujitsu/app_blog/tree/master/openapi-202003/part1（GitHub, Inc.）

• 注1
  ここで言う「API管理」とは、いわゆる、サービスディスカバリーのようなことではありません。

マイクロサービスでのAPI管理

マイクロサービスアーキテクチャーでシステムを構築する際は、一般的にはサービス間をAPIでつないでいきます。サービス提供者は、APIの仕様を、サービス利用者に提供します。サービス利用者は、サービスの中身について知る必要はなく、提供されたAPIの仕様にしたがって呼出しさえすれば、サービスを利用することができます。したがって、重要なのは、サービス提供者が、サービスの内容に合致した正しい仕様を提供することです。また、サービス内容を更新し、APIに変更が生じる場合は、タイムリーにサービス利用者に変更した仕様を提供することです。

新しくサービスを作成する際には、まじめに仕様書を作ることが多いですが、サービスを更新したときに、同時に仕様書も更新することは億劫になりがちです。また、サービスの数が少ないときはいいですが、マイクロサービスアーキテクチャーのように、数千、数万のサービスを管理するのはたいへんです。さらに、年月が経つと、当時開発した人が現場からいなくなり、仕様書もない状態で誰もメンテナンスできない、ということもあります。

OpenAPI

OpenAPI Specificationとは、REST APIの仕様を定義するための標準ルールで、特定のプログラミング言語に依存しない仕様となっています。また、仕様書はYAMLやJSON形式で記述可能なため、仕様書をプログラム的に扱うことができます。そのため、人手で管理する必要がなくなり、APIの数がいくら増えても、管理コストを抑えることができます。

OpenAPIでは、さまざまなツールが開発され利用できますが、本シリーズでは、Swagger UI（OpenAPI形式の仕様書を表示するツール）と、OpenAPI Generator（OpenAPI形式の仕様書からHTMLやプログラムコードなどを作成するツール）を使います。

MicroProfile OpenAPI

MicroProfile OpenAPIとは、OpenAPIをJavaのインターフェイスで使うもので、JAX-RSアプリケーションからOpenAPI形式のドキュメントを作成することができます。

MicorProfile OpenAPIで用意しているさまざまなannotationをJAX-RSのコードに付与することで、OepnAPIの仕様書を作成できますが、第1回では、これらのannotationは一切使用せずに、素のJAX-RSコードだけで、仕様書を作成します。すなわち、想定としては、すでに既存の動作しているJAX-RSプログラムがあり、それらのコードを修正することなく、API仕様書を作成します。

既存のJAX-RSからOpenAPI仕様書を作成する

ソースの準備

使用するJAX-RSのプログラムは以下のようなHelloWorldです。

App.java

package com.fujitsu.launcher.demo202003;
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/demo")
public class App extends Application {
}

Hello.java

package com.fujitsu.launcher.demo202003;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("hello")
public class Hello {

  @GET
  public String hello() {
    return "Hello World !";
  }
}

プログラムのビルドについては、こちらにmavenプロジェクトを用意していますので、参照ください。

HelloWorldの起動

MicroProfile OpenAPIを使用するために、MicroProfileの実装の一つである、Launcherを用意します。ここでは、以下より、2.0-b01版をダウンロードして利用します。

• https://github.com/fujitsu/launcher/releases/download/2.0-b01/launcher-2.0-b01.jar（GitHub, Inc.）

Launcherの使い方は、ダウンロードした「launcher-2.0-b01.jar」を任意の場所に置いて、javaコマンドの-jarオプションに指定する（インストール作業不要）だけです。詳細なLauncherの使用方法は、ドキュメントを参照してください。

$ java -jar launcher-2.0-b01.jar --deploy Hello.war

通常、MicroProfileアプリケーションの起動はこれでいいのですが、今回は、仕様書を生成したいパッケージ名をmp.openapi.scan.packagesプロパティに指定して仕様書を作成します。

$ java -Dmp.openapi.scan.packages=com.fujitsu.launcher.demo202003 -jar launcher-2.0-b01.jar --deploy Hello.war

仕様書の確認

アプリケーションはこれまで通り、設定したエンドポイントにアクセスできます。

図1

OpenAPI形式の仕様は、「/openapi」でアクセスすることで取得可能です。

図2

HTMLの作成

JSONやYAML形式は、プログラム的に扱うには都合が良いですが、人が目で見るにはいささか見難くくなります。そこで、OpenAPI Generatorを使い、YAML形式の仕様書から、HTMLを生成します。OepnAPI Generatorは、GitHubで開発されており、バイナリーはMaven Centralから取得することができます。今回は、バージョン4.2.3を使用します。以下のように、-iオプションに、OpenAPI形式の仕様を指定し、-gオプションに「html」を指定することで、HTMLを生成することができます。

$ java -jar openapi-generator-cli-4.2.3.jar generate -i http://localhost:8080/openapi -g html

カレントディレクトリーに、index.htmlができるので、それをブラウザーで開きます。

図3

このように、限定的な情報ではありますが、APIのエンドポイントごとに、return typeやレスポンスヘッダーの情報などを自動生成することができます。

Swagger UI

HTMLにすることで、だいぶ見やすくなりましたが、generatorを使って、いちいちHTMLに変換するのも面倒です。そこで、MicroProfileの拡張機能を使い、自動的にSwagger UIに対応させてみます。MicroProfileの拡張機能を使うには、以下のdependencyをpom.xmlに追加します。

<dependency>
  <groupId>org.microprofile-ext.openapi-ext</groupId>
  <artifactId>openapi-ui</artifactId>
  <version>1.1.2</version>
</dependency>

あとは、これまでと同様にmavenでビルドします。Swagger UIへのアクセスは、「<アプリケーションのベースURI>/openapi-ui」でアクセスします。

図4

「/demo/hello」のところをクリックすると、以下のような詳細情報を見ることができます。

図5

まとめと予告

今回Part1では、MicroProfile OpenAPIのannotationは一切使わず、ドキュメントを生成することができました。このことは、すでに存在するJAX-RSのプログラムの中身を見なくても、ある程度のドキュメントを生成し、メンテナンスに役立てることができることを意味します。

図6

次回Part2では、MicroProfile OpenAPIを使って、より詳細なドキュメントを作成する方法を見ていきます。