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 関連の連絡先に使用するメールアドレス。 |
| 文字列 | API 関連の連絡先に使用する個人または組織の名前。 |
| 文字列 | API 関連の問い合わせ先の Web サイトへの URL。 |
| ブール値 |
アプリケーションに複数の |
| 文字列 | コンテキストリストに表示される CamelContext ID のフィルターパターン。正規表現を指定し、ワイルドカードとして * を使用することができます。これは、Camel Intercept 機能で使用されるのと同じパターンマッチング機能です。 |
| 文字列 | API に適用されるライセンス名。 |
| 文字列 | API に適用されるライセンスの URL。 |
| 文字列 |
ドキュメントを生成する REST API が使用可能なパスを設定します (例: |
| 文字列 | API の利用規約への URL。 |
| 文字列 | アプリケーションの名前。 |
| 文字列 | API のバージョン。デフォルトは 0.0.0 です。 |
| 文字列 |
必須。REST サービスが利用できるパスを設定します。相対パスで指定します。たとえば、 |
| ブール値 |
CORS (オリジン間リソース共有) を有効にするかどうか。これにより、CORS は REST API ドキュメントを閲覧する場合のみ有効になり、REST サービスにアクセスする場合には有効になりません。デフォルトは false です。この表の後で説明するように、代わりに |
| 文字列 |
OpenAPI サービスが実行されているホストの名前を指定します。デフォルトでは、 |
| 文字列 |
使用するプロトコルスキーム。複数の値はコンマで区切ります (例: |
| 文字列 | 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-java
は camel-openapi-java
モジュールの使用方法を実証します。
Apache Camel 2.x ディストリビューションで、camel-example-swagger-cdi
および camel-example-swagger-java
は camel-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
も参照してください。