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

第174章 Swagger Java

Swagger Java コンポーネント
リンクのコピー

Camel 2.16 以降で利用可能
Rest DSL は、Swagger を使用して REST サービスとその API を公開するために使用される camel-swagger-java モジュールと統合できます。
Maven ユーザーは、このコンポーネントの以下の依存関係を pom.xml に追加する必要があります。
Camel 2.16 以降、swagger コンポーネントは純粋に Java ベースであり、そのコンポーネントになります。 
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-swagger-java</artifactId>
    <version>2.17.0.redhat-630xxx</version>
    <!-- use the same version as your Camel core version -->
</dependency>
Copy to Clipboard Toggle word wrap
camel-swagger-java モジュールはサーブレットとして、または REST コンポーネントから直接使用することもできます（サーブレットは必要ありません）。
Apache Camel ディストリビューションの例ディレクトリー( camel-example-swagger-cdi )を参照してください。

Swagger をサーブレットとして使用
リンクのコピー

以下のように web.xml で swagger を設定します。 
  <servlet>
 
    <servlet-name>SwaggerServlet</servlet-name>
    <servlet-class>org.apache.camel.swagger.servlet.RestSwaggerServlet</servlet-class>

    <init-param>
      <!-- we specify the base.path using relative notation, that means the actual path will be calculated at runtime as
           http://server:port/contextpath/rest -->
      <param-name>base.path</param-name>
      <param-value>rest</param-value>
    </init-param>
    <init-param>
      <!-- we specify the api.path using relative notation, that means the actual path will be calculated at runtime as
           http://server:port/contextpath/api-docs -->
      <param-name>api.path</param-name>
      <param-value>api-docs</param-value>
    </init-param>

    <init-param>
      <param-name>api.version</param-name>
      <param-value>1.2.3</param-value>
    </init-param>
    <init-param>
      <param-name>api.title</param-name>
      <param-value>User Services</param-value>
    </init-param>
    <init-param>
      <param-name>api.description</param-name>
      <param-value>Camel Rest Example with Swagger that provides an User REST service</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <!-- swagger api -->
  <servlet-mapping>
    <servlet-name>SwaggerServlet</servlet-name>
    <url-pattern>/api-docs/*</url-pattern>
  </servlet-mapping>
Copy to Clipboard Toggle word wrap

rest-dsl での Swagger の使用
リンクのコピー

rest-dsl から swagger api を有効にするには、apiContextPath dsl を以下のように設定します。 
public class UserRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        // configure we want to use servlet as the component for the rest DSL
        // and we enable json binding mode
        restConfiguration().component("netty4-http").bindingMode(RestBindingMode.json)
            // and output using pretty print
            .dataFormatProperty("prettyPrint", "true")
            // setup context path and port number that netty will use
            .contextPath("/").port(8080)
            // add swagger api-doc out of the box
            .apiContextPath("/api-doc")
                .apiProperty("api.title", "User API").apiProperty("api.version", "1.2.3")
                // and enable CORS
                .apiProperty("cors", "true");

        // this user REST service is json only
        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 モジュールは、以下のオプションを使用して設定できます。サーブレットを使用して設定するには、上記のように init-param を使用します。rest-dsl で直接設定する場合は、enableCORS, host,contextPath, dsl などの適切な方法を使用します。api.xxx のオプションは、apiProperty dsl を使用して設定されます。
Expand
オプション
タイプ
説明
cors ブール値 CORS を有効にするかどうか。これにより、api ブラウザーの CORS のみが有効になり、REST サービスへの実際のアクセスは有効ではないことに注意してください。デフォルトは false です。このオプションを使用する代わりに、CorsFilte を使用することが推奨されます。詳細は、以下を参照してください。
swagger.version 文字列 Swagger 仕様バージョン。デフォルトは 2.0 です。
host 文字列 ホスト名を設定します。camel-swagger-java が設定されていない場合、名前は localhost ベースとして計算されます。
スキーマ 文字列 使用するプロトコルスキーム。"http,https" のように、複数の値をコンマで区切ることができます。デフォルト値は「http」です。このオプションは schemes という名前であるため、Camel 2.17 以降では 非推奨 となりました。
schemes 文字列 Camel 2.17: 使用するプロトコルスキーム"http,https" のように、複数の値をコンマで区切ることができます。デフォルト値は「http」です。
base.path 文字列
必須: REST サービスが利用できるベースパスを設定します。パスは相対(http/https で開始されない)であり、camel-swagger-java は実行時に絶対ベースパスを計算します。 
protocol://host:port/context-path/base.path
Copy to Clipboard Toggle word wrap
api.path 文字列
API が利用できるパスを設定します（例：/api-docs）。パスは相対(http/https で開始されない)であり、camel-swagger-java は実行時に絶対ベースパスを計算します。 
protocol://host:port/context-path/api.path
Copy to Clipboard Toggle word wrap
そのため、相対パスの使用ははるかに簡単です。例については、上記を参照してください。
api.version 文字列 API のバージョン。デフォルトは 0.0.0 です。
api.title 文字列 アプリケーションのタイトル。
api.description 文字列 アプリケーションの簡単な説明。
api.termsOfService 文字列 API の利用規約への URL。
api.contact.name 文字列 連絡先に使用する個人または組織の名前
api.contact.email 文字列 API 関連の対応に使用するメール。
api.contact.url 文字列 API 関連の問い合わせ先の Web サイトへの URL。
api.license.name 文字列 API に使用されるライセンス名。
api.license.url 文字列 API に使用されるライセンスへの URL。
apiContextIdListing boolean REST サービスを持つ JVM のすべての CamelContext 名の一覧表示を許可するかどうか。有効にすると、api-doc のルートパスにより、すべてのコンテキストが一覧表示されます。無効にするとコンテキスト ID が表示されず、api-doc のルートパスは現在の CamelContext を一覧表示します。デフォルトは false です。
apiContextIdPattern 文字列 コンテキストリストに示されている CamelContext 名をフィルターできるようにするパターン。このパターンは正規表現と * をワイルドカードとして使用します。Intercep で使用されるのと同じパターンの一致

CorsFilter
リンクのコピー

swagger ui を使用して REST API を表示する場合は、CORS のサポートを有効にする必要がある場合があります。これは、swagger ui がホストされ、実際の RESTapis 以外のホスト名/ポートで実行されている場合に必要になります。これを行う場合は、swagger ui が元の CORS (CORS)全体で REST リソースにアクセスできるようにする必要があります。CorsFilter は、CORS を有効にするために必要な HTTP ヘッダーを追加します。
CORS を使用するには、以下のフィルター org.apache.camel.swagger.servlet.RestSwaggerCorsFilter を web.xml に追加します。 
  <!-- enable CORS filter so people can use swagger ui to browse and test the 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
CorsFilter は、すべてのリクエストに以下のヘッダーを設定します。
  • 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
これは非常に単純な CORS フィルターであることに注意してください。特定のクライアントに異なるヘッダー値を設定するには、より高度なフィルターを使用してヘッダー値を設定する必要がある場合があります。または、特定のクライアントなどをブロックします。

ContextIdListing enabled
リンクのコピー

contextIdListing が有効になっている場合、そのタスクは、同じ JVM で実行されている CamelContext をすべて検出します。これらのコンテキストはルートパスに一覧表示されます（例：'/api-docs'）は、名前の簡単なリストとして json 形式になります。swagger のドキュメントにアクセスするには、context-path に 'api-docs/myCamel' などの Camel コンテキスト ID を追加する必要があります。apiContextIdPattern オプションは、このリストの名前をフィルターするために使用できます。

JSON または Yaml
リンクのコピー

Camel 2.17 以降で利用可能
camel-swagger-java モジュールは、設定設定なしで JSon と Yaml の両方をサポートします。リクエスト URL に /swagger.json または /swagger.yaml のいずれかを使用して、返すものを指定できます。指定がない場合は、json または yaml を許可するかどうかを検出するために HTTP Accept ヘッダーが使用されます。両方が受け入れられるか、または何も受け入れられないと、json がデフォルトの形式として返されます。

例
リンクのコピー

Apache Camel ディストリビューションでは、この Swagger コンポーネントの使用を示す camel-example-swagger-cdi および camel-example-swagger-java が含まれています。
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

Theme

© 2025 Red Hat