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
コンポーネントに依存関係を追加します。
CamelContext での Swagger の有効化 リンクのコピーリンクがクリップボードにコピーされました!
REST DSL で Swagger API を使用できるようにするには、apiContextPath()
を呼び出して、Swagger で生成された API ドキュメントのコンテキストパスを設定します。以下に例を示します。
Swagger モジュールの設定オプション リンクのコピーリンクがクリップボードにコピーされました!
下表のオプションを使用して、Swagger モジュールを設定することができます。以下のようにオプションを設定します。
-
camel-swagger-java
モジュールをサーブレットとして使用している場合は、web.xml
ファイルを編集し、設定する設定オプションごとにinit-param
要素を指定してオプションを設定します。 -
Camel REST コンポーネントから
camel-swagger-java
モジュールを使用している場合は、enableCORS()
、host()
、またはcontextPath()
などの適切なRestConfigurationDefinition
メソッドを呼び出してオプションを設定します。api.xxx
オプションをRestConfigurationDefinition.apiProperty()
メソッドで設定します。
オプション | タイプ | 説明 |
---|---|---|
| String | API 関連の連絡先に使用するメールアドレス。 |
| String | API 関連の連絡先に使用する個人または組織の名前。 |
| String | API 関連の問い合わせ先の Web サイトへの URL。 |
| ブール値 |
アプリケーションに複数の |
| String | コンテキストリストに表示される CamelContext ID のフィルターパターン。正規表現を指定し、ワイルドカードとして * を使用することができます。これは、Camel Intercept 機能で使用されるのと同じパターンマッチング機能です。 |
| String | API に適用されるライセンス名。 |
| String | API に適用されるライセンスの URL。 |
| String |
ドキュメントを生成する REST API が使用可能なパスを設定します (例: |
| String | API の利用規約への URL。 |
| String | アプリケーションの名前。 |
| String | API のバージョン。デフォルトは 0.0.0 です。 |
| String |
必須。REST サービスが利用できるパスを設定します。相対パスで指定します。たとえば、 |
| ブール値 |
CORS (オリジン間リソース共有) を有効にするかどうか。これにより、CORS は REST API ドキュメントを閲覧する場合のみ有効になり、REST サービスにアクセスする場合には有効になりません。デフォルトは false です。この表の後で説明するように、代わりに |
| String |
Swagger サービスが実行されているホストの名前を指定します。デフォルトでは、 |
| String |
使用するプロトコルスキーム。複数の値はコンマで区切ります (例: |
| String | Swagger 仕様のバージョン。デフォルトは 2.0 です。 |
CORS フィルターの使用した CORS サポートの有効化 リンクのコピーリンクがクリップボードにコピーされました!
Swagger ユーザーインターフェイスを使用して REST API ドキュメントを表示する場合は、CORS (オリジン間リソース共有) のサポートを有効にする必要があるでしょう。このサポートは、Swagger ユーザーインターフェイスがホストされていて、REST API が実行されているホスト名/ポートとは異なる場合に必要です。
CORS のサポートを有効にするには、RestSwaggerCorsFilter
を web.xml
ファイルに追加します。CORS フィルターには、CORS を有効にする HTTP ヘッダーを追加します。以下に例を示します。
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 パスパラメーターに関する情報を補足する方法を示しています。
以下は 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})")
.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
も指定する必要があります。以下に例を示します。
以下は 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")
.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
も参照してください。