4.5. OpenAPI Integration

OpenAPI サービスを使用して、CamelContext ファイルの REST 定義ルートおよびエンドポイントの API ドキュメントを作成できます。これには、純粋に Java ベースの camel-openapi-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>

Camel REST DSL で OpenAPI の使用を有効にするには、api ContextPath（） を呼び出して 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 モジュールを設定できます。以下のようにオプションを設定します。

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

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

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

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 も参照してください。