Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

4.5. Swagger との統合

概要
リンクのコピー

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

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

<dependency>
   <groupId>org.apache.camel</groupId>
   <artifactId>camel-swagger-java</artifactId>
   <version>x.x.x</version>
   <!-- Specify the version of your camel-core module. -->
</dependency>
Copy to Clipboard Toggle word wrap

CamelContext での Swagger の有効化
リンクのコピー

REST DSL で Swagger API を使用できるようにするには、apiContextPath() を呼び出して、Swagger で生成された 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 Swagger-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");
    }
}
Copy to Clipboard Toggle word wrap

Swagger モジュールの設定オプション
リンクのコピー

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

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

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 の場合、Swagger は CamelContext のルートパス (たとえば /api-docs) で ID 一覧を JSON 形式のリストとして公開します。Swagger で生成されたドキュメントにアクセスするには、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-swagger-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-swagger-java モジュールは、ランタイム時に protocol://host:port/context-path/base.path の形式で絶対パスを計算します。

cors

ブール値

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

host

String

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

schemes

String

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

swagger.version

String

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

CORS フィルターの使用した CORS サポートの有効化
リンクのコピー

Swagger ユーザーインターフェイスを使用して REST API ドキュメントを表示する場合は、CORS (オリジン間リソース共有) のサポートを有効にする必要があるでしょう。このサポートは、Swagger ユーザーインターフェイスがホストされていて、REST API が実行されているホスト名/ポートとは異なる場合に必要です。

CORS のサポートを有効にするには、RestSwaggerCorsFilter を web.xml ファイルに追加します。CORS フィルターには、CORS を有効にする HTTP ヘッダーを追加します。以下に例を示します。 

<!-- Enable CORS filter to allow use of Swagger UI for browsing and testing APIs. -->
<filter>
     <filter-name>RestSwaggerCorsFilter</filter-name>
     <filter-class>org.apache.camel.swagger.rest.RestSwaggerCorsFilter</filter-class>
</filter>
<filter-mapping>
     <filter-name>RestSwaggerCorsFilter</filter-name>
     <url-pattern>/api-docs/*</url-pattern>
     <url-pattern>/rest/*</url-pattern>
</filter-mapping>
Copy to Clipboard Toggle word wrap

RestSwaggerCorsFilter は、すべてのリクエストに対して以下のヘッダーを設定します。

  • Access-Control-Allow-Origin= *
  • access-Control-Allow-Methods = GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT, PATCH
  • Access-Control-Max-Age = 3600'
  • Access-Control-Allow-Headers = Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers

RestSwaggerCorsFilter は単純なフィルターです。特定のクライアントをブロックしたり、特定のクライアントに対して異なるヘッダー値を設定したりする必要がある場合は、複雑なフィルターが必要になる可能性があります。

JSON または YAML 形式の出力
リンクのコピー

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

例
リンクのコピー

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

Swagger で生成されたドキュメントの充実
リンクのコピー

Camel 2.16 以降では、名前、説明、データ型、パラメーター型などのパラメーター詳細を定義することで、Swagger で生成されたドキュメントを充実することができます。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>
Copy to Clipboard Toggle word wrap

以下は 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})")
Copy to Clipboard Toggle word wrap

名前が 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>
Copy to Clipboard Toggle word wrap

以下は 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")
Copy to Clipboard Toggle word wrap

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

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat