4.5. OpenAPI インテグレーション

概要

OpenAPI サービスを使用して、CamelContext 内の REST 定義されたルートやエンドポイントの API ドキュメントを生成することができます。これを行うには、camel-openapi-java モジュール (純粋な Java ベースのモジュール) で Camel REST DSL を使用します。camel-openapi-java モジュールは CamelContext と統合したサーブレットを作成し、各 REST エンドポイントから情報を取得して JSON または YAML 形式の API ドキュメントを生成します。

Maven を使用する場合は、pom.xml ファイルを編集して camel-openapi-java コンポーネントに依存関係を追加します。

<dependency>
   <groupId>org.apache.camel</groupId>
   <artifactId>camel-openapi-java</artifactId>
   <version>x.x.x</version>
   <!-- Specify the version of your camel-core module. -->
</dependency>

CamelContext での OpenAPI の有効化

Camel REST DSL で OpenAPI を使用できるようにするには、apiContextPath() を呼び出して、OpenAPI で生成された API ドキュメントのコンテキストパスを設定します。以下に例を示します。

public class UserRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        // Configure the Camel REST DSL to use the netty4-http component:
        restConfiguration().component("netty4-http").bindingMode(RestBindingMode.json)
            // Generate pretty print output:
            .dataFormatProperty("prettyPrint", "true")
            // Set the context path and port number that netty will use:
            .contextPath("/").port(8080)
            // Add the context path for the OpenAPI-generated API documentation:
            .apiContextPath("/api-doc")
                .apiProperty("api.title", "User API").apiProperty("api.version", "1.2.3")
                // Enable CORS:
                .apiProperty("cors", "true");

        // This user REST service handles only JSON files:
        rest("/user").description("User rest service")
            .consumes("application/json").produces("application/json")
            .get("/{id}").description("Find user by id").outType(User.class)
                .param().name("id").type(path).description("The id of the user to get").dataType("int").endParam()
                .to("bean:userService?method=getUser(${header.id})")
            .put().description("Updates or create a user").type(User.class)
                .param().name("body").type(body).description("The user to update or create").endParam()
                .to("bean:userService?method=updateUser")
            .get("/findAll").description("Find all users").outTypeList(User.class)
                .to("bean:userService?method=listUsers");
    }
}

OpenAPI モジュールの設定オプション

下表のオプションを使用して、OpenAPI モジュールを設定することができます。以下のようにオプションを設定します。

  • camel-openapi-java モジュールをサーブレットとして使用している場合は、web.xml ファイルを編集し、設定する設定オプションごとに init-param 要素を指定してオプションを設定します。
  • Camel REST コンポーネントから camel-openapi-java モジュールを使用している場合は、enableCORS()host()、または contextPath() などの適切な RestConfigurationDefinition メソッドを呼び出してオプションを設定します。api.xxx オプションを RestConfigurationDefinition.apiProperty() メソッドで設定します。
オプション説明

api.contact.email

String

API 関連の連絡先に使用するメールアドレス。

api.contact.name

String

API 関連の連絡先に使用する個人または組織の名前。

api.contact.url

String

API 関連の問い合わせ先の Web サイトへの URL。

apiContextIdListing

ブール値

アプリケーションに複数の CamelContext オブジェクトを使用している場合、デフォルトの動作では、現在の CamelContext のみに REST エンドポイントが一覧表示されます。REST サービスを実行している JVM で、実行されている個々の CamelContext の REST エンドポイントのリストが必要な場合は、このオプションを true に設定します。apiContextIdListing が true の場合、OpenAPI はルートパスの CamelContext ID (たとえば /api-docs) を JSON 形式の名前のリストとして公開します。OpenAPI で生成されたドキュメントにアクセスするには、REST コンテキストパスを CamelContext ID に追加します (たとえば api-docs/myCamel)。apiContextIdPattern オプションを使用して、この出力リストの名前をフィルターリングできます。

apiContextIdPattern

String

コンテキストリストに表示される CamelContext ID のフィルターパターン。正規表現を指定し、ワイルドカードとして * を使用することができます。これは、Camel Intercept 機能で使用されるのと同じパターンマッチング機能です。

api.license.name

String

API に適用されるライセンス名。

api.license.url

String

API に適用されるライセンスの URL。

api.path

String

ドキュメントを生成する REST API が使用可能なパスを設定します (例: /api-docs)。相対パスで指定します。たとえば、http または https は指定しないでください。camel-openapi-java モジュールは、ランタイム時に protocol://host:port/context-path/api-path の形式で絶対パスを計算します。

api.termsOfService

String

API の利用規約への URL。

api.title

String

アプリケーションの名前。

api.version

String

API のバージョン。デフォルトは 0.0.0 です。

base.path

String

必須。REST サービスが利用できるパスを設定します。相対パスで指定します。たとえば、http または https は指定しないでください。camel-openapi-java モジュールは、ランタイム時に protocol://host:port/context-path/base.path の形式で絶対パスを計算します。

cors

ブール値

CORS (オリジン間リソース共有) を有効にするかどうか。これにより、CORS は REST API ドキュメントを閲覧する場合のみ有効になり、REST サービスにアクセスする場合には有効になりません。デフォルトは false です。この表の後で説明するように、代わりに CorsFilter オプションを使用することをお勧めします。

host

String

OpenAPI サービスが実行されているホストの名前を指定します。デフォルトでは、localhost に基づいてホスト名が計算されます。

schemes

String

使用するプロトコルスキーム。複数の値はコンマで区切ります (例: "http,https".)。デフォルトは http です。

opeapi.version

String

OpenAPI 仕様のバージョン。デフォルトは 3.0 です。

JSON または YAML 形式の出力

Camel 3.1 以降、camel-openapi-java モジュールは JSON と YAML 形式の両方の出力をサポートしています。必要な出力を指定するには、リクエスト URL に /openapi.json または /openapi.yaml を追加します。リクエスト URL に形式が指定されていない場合、camel-openapi-java モジュールは HTTP Accept ヘッダーをチェックして JSON または YAML を許可するかどうかを検出します。両方が受け入れられるか、両方が受け入れられないと検知された場合は、デフォルトの JSON 形式が出力されます。

Apache Camel 3.x ディストリビューションで、camel-example-openapi-cdi および camel-example-openapi-javacamel-openapi-java モジュールの使用方法を実証します。

Apache Camel 2.x ディストリビューションで、camel-example-swagger-cdi および camel-example-swagger-javacamel-swagger-java モジュールの使用方法を実証します。

OpenAPI で生成されたドキュメントの充実

Camel 3.1 以降では、名前、説明、データ型、パラメーター型などのパラメーター詳細を定義することで、OpenAPI で生成されたドキュメントを充実することができます。XML DSL を使用している場合は、param 要素を指定してこれらの情報を追加します。以下の XML DSL の例は、ID パスパラメーターに関する情報を補足する方法を示しています。

<!-- This is a REST GET request to view information for the user with the given ID: -->
<get uri="/{id}" outType="org.apache.camel.example.rest.User">
     <description>Find user by ID.</description>
     <param name="id" type="path" description="The ID of the user to get information about." dataType="int"/>
     <to uri="bean:userService?method=getUser(${header.id})"/>
</get>

以下は Java DSL の例です。

.get("/{id}").description("Find user by ID.").outType(User.class)
   .param().name("id").type(path).description("The ID of the user to get information about.").dataType("int").endParam()
   .to("bean:userService?method=getUser(${header.id})")

名前が body のパラメーターを定義する場合は、そのパラメーターの型として body も指定する必要があります。以下に例を示します。

<!-- This is a REST PUT request to create/update information about a user. -->
<put type="org.apache.camel.example.rest.User">
     <description>Updates or creates a user.</description>
     <param name="body" type="body" description="The user to update or create."/>
     <to uri="bean:userService?method=updateUser"/>
</put>

以下は Java DSL の例です。

.put().description("Updates or create a user").type(User.class)
     .param().name("body").type(body).description("The user to update or create.").endParam()
     .to("bean:userService?method=updateUser")

Apache Camel ディストリビューションの examples/camel-example-servlet-rest-tomcat も参照してください。