2.14.12 OpenAPI仕様書からHCSCコンポーネントを作成するOpenAPI仕様書インポート機能
OpenAPI仕様書インポート機能とは，OpenAPI仕様書をHTTP受付やビジネスプロセスなどのHCSCコンポーネントに変換する機能です。
OpenAPI仕様書インポート機能を利用して作成したHCSCコンポーネントの定義ファイルをサービス定義のインポート機能を使用して，開発環境に取り込みます。
- 〈この項の構成〉
(1) OpenAPI仕様書インポート機能の概要
OpenAPI仕様書をHCSCコンポーネントに変換する流れを次に示します。
|
|
![[図データ]](GRAPHICS/ZC021312.GIF)
-
Swagger Editorなどのツールを使用し，OpenAPI仕様書を作成します。
HCSCコンポーネントとOpenAPI仕様書との対応については，「(3) HCSCコンポーネントとOpenAPI仕様書との対応」を参照してください。
-
OpenAPI仕様書インポート機能を利用して，OpenAPI仕様書をHCSCコンポーネントの定義ファイル（サービス定義XMLファイル，電文のスキーマファイル，独自定義ファイル）に変換します。
OpenAPI仕様書の変換については，「(5) OpenAPI仕様書の変換」を参照してください。
-
サービス定義のインポート機能を利用して，開発環境にHCSCコンポーネント（HTTP受付，ビジネスプロセス）を作成します。
サービス定義のインポート機能については，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「6.4 サービス定義のインポート」を参照してください。
OpenAPI仕様書から作成されたHCSCコンポーネントの生成イメージを次に示します。
|
|
![[図データ]](GRAPHICS/ZC021315.GIF)
OpenAPI仕様書でのPath ItemはHTTP受付，Operationはビジネスプロセスにそれぞれ対応します。
(2) 前提条件
OpenAPI仕様書インポート機能を使用する場合の前提条件を次に示します。
-
OpenAPI仕様書インポート機能で対応するOpenAPI Specificationのバージョンは3.0以降です。
-
OpenAPI仕様書インポート機能で使用する前提OSSを次の表に示します。
前提OSSのjarファイルは，次に示すディレクトリの下に配置してください。
<サービスプラットフォームのインストールディレクトリ>\CSCTE\lib\external
表2‒64 前提OSS一覧 項番
OSS名
バージョン
jarファイル名
ライセンス
1
swagger-parser-v3
2.0.21
swagger-parser-v3-2.0.21.jar
Apache License 2.0
2
swagger-models
(io.swagger.core.v3)
2.1.4
swagger-models-2.1.4.jar
Apache License 2.0
3
swagger-core
(io.swagger.core.v3)
2.1.4
swagger-core-2.1.4.jar
Apache License 2.0
4
jakarta.xml.bind-api
2.3.3
jakarta.xml.bind-api-2.3.3.jar
EDL 1.0
5
jakarta.activation-api
1.2.2
jakarta.activation-api-1.2.2.jar
EDL 1.0
6
commons-lang3
3.9
commons-lang3-3.9.jar
Apache License 2.0
7
slf4j-api
1.7.25
slf4j-api-1.7.25.jar
MIT
8
jackson-datatype-jsr310
2.11.2
jackson-datatype-jsr310-2.11.2.jar
Apache License 2.0
9
swagger-annotations
2.1.4
swagger-annotations-2.1.4.jar
Apache License 2.0
10
jakarta.validation-api
2.0.2
jakarta.validation-api-2.0.2.jar
Apache License 2.0
11
swagger-parser-core
2.0.21
swagger-parser-core-2.0.21.jar
Apache License 2.0
12
commons-io
2.7
commons-io-2.7.jar
Apache License 2.0
13
jackson-annotations
2.11.2
jackson-annotations-2.11.2.jar
Apache License 2.0
14
jackson-databind
2.11.2
jackson-databind-2.11.2.jar
Apache License 2.0
15
jackson-core
2.11.2
jackson-core-2.11.2.jar
Apache License 2.0
16
jackson-dataformat-yaml
2.11.2
jackson-dataformat-yaml-2.11.2.jar
Apache License 2.0
17
snakeyaml
1.26
snakeyaml-1.26.jar
Apache License 2.0
18
swagger-inflector
2.0.5
swagger-inflector-2.0.5.jar
Apache License 2.0
19
swagger-core
(io.swagger)
1.6.2
swagger-core-1.6.2.jar
Apache License 2.0
20
swagger-models
(io.swagger)
1.6.2
swagger-models-1.6.2.jar
Apache License 2.0
(3) HCSCコンポーネントとOpenAPI仕様書との対応
OpenAPI仕様書インポート機能では，OpenAPI仕様書を変換して，HCSCコンポーネントのHTTP受付（呼出先選択）とビジネスプロセスを作成できます。
OpenAPI仕様書をHCSCコンポーネントに変換したときの例を次に示します。
|
|
![[図データ]](GRAPHICS/ZC021313.GIF)
OpenAPI仕様書インポート機能で作成したHTTP受付（呼出先選択）には，OpenAPI仕様書の定義に従ったHTTPクライアントから接続できます。
HTTP受付（呼出先選択）およびビジネスプロセスと，OpenAPI仕様書について，次に説明します。
(a) HTTP受付（呼出先選択）とOpenAPI仕様書との対応
HTTP受付（呼出先選択）とOpenAPI仕様書との対応を次の表に示します。
|
項番 |
HTTP受付（呼出先選択）の設定 |
OpenAPI仕様書のフィールド |
サービス定義XML |
|||
|---|---|---|---|---|---|---|
|
タグ |
設定値 |
フィールドが定義されていない場合の設定値 |
||||
|
1 |
受付名 |
Path Item#x-csd-reception-name |
/service-definition/selectable-reception/name |
Path Item#x-csd-reception-nameに設定した名称 |
デフォルトの受付名を設定します。 |
|
|
2 |
受付ID |
Path Item#x-csd-reception-id |
/service-definition/selectable-reception/reception-id |
Path Item#x-csd-reception-idに設定したID |
デフォルトのIDを設定します。 |
|
|
3 |
オペレーション |
Path Item#get |
/service-definition/selectable-reception/protocol-definition/operations/operation/name |
GET |
operation要素を省略します。 |
|
|
4 |
Path Item#put |
PUT |
||||
|
5 |
Path Item#post |
POST |
||||
|
6 |
Path Item#delete |
DELETE |
||||
|
7 |
Path Item#options |
OPTIONS |
||||
|
8 |
Path Item#head |
HEAD |
||||
|
9 |
要求電文ボディの電文フォーマット |
Request Body#content |
/service-definition/selectable-reception/protocol-definition/operations/operation/input-body/format/file-path |
XSDのファイルパス※1 |
file-path要素を省略します。 |
|
|
10 |
応答電文ボディの電文フォーマット |
Response#content |
/service-definition/selectable-reception/protocol-definition/operations/operation/output-body/format/file-path |
XSDのファイルパス※2 |
file-path要素を省略します。 |
|
|
11 |
HTTP受付定義 |
− |
/service-definition/selectable-reception/protocol-definition/custom-definition-files/file-path |
HTTP受付定義のファイルパス |
− |
|
|
12 |
urecp-http.context-root |
Paths#/{path} Path Item#servers OpenAPI#servers |
− |
{path}の内容 （テンプレートマッピング部分は使用しません） |
HCSCコンポーネントを作成するための情報がないため，エラーメッセージ（KECT94017-E）が出力されます。 |
|
|
13 |
httprecp.request.switchover.json-transfer.mode |
Request Body#content |
− |
true※3 |
プロパティを省略します（=false）。 |
|
|
14 |
httprecp.response.switchover.json-transfer.mode |
Response#content |
− |
true※4 |
プロパティを省略します（=false）。 |
|
|
15 |
httprecp.switchover.pass-through.mode |
Response#content |
− |
true※5 |
プロパティを省略します（=false）。 |
|
|
16 |
HTTP受付サービス選択定義 |
Path Item |
/service-definition/selectable-reception/protocol-definition/custom-definition-files/file-path |
HTTP受付サービス選択定義のファイルパス |
− |
|
|
17 |
<HTTPメソッド名>=<ビジネスプロセス名> |
Path Item |
− |
項番3〜8のオペレーション=ビジネスプロセス名 |
プロパティを省略します。 |
|
（凡例）−：該当しません。
- 注※1
-
Media Typeがjson，またはxmlの場合にXSDを生成し，ファイルパスを設定します。次の場合はfile-path要素を省略します。
・Media Typeがjson，またはxml以外の場合
・1つのRequestBody内にMedia Typeが複数定義されていた場合
・Media Typeがmultipartの場合
- 注※2
-
Media Typeがjson，またはxmlの場合にXSDを生成し，ファイルパスを設定します。次の場合はfile-path要素を省略します。
・Media Typeがjson，またはxml以外の場合
・1つのResponse内にMedia Typeが複数定義されていた場合
・Media Typeがmultipartの場合
また，ResponseがResponses内で複数定義されていた場合は要素を省略します。
- 注※3
-
RequestBodyのMedia Typeがjsonである場合はtrueを設定します。json以外の場合はプロパティを省略します（=false）。
Path Item内の各オペレーションに定義されているRequestBodyに1つでもjsonのMedia Typeがあればtrueとなります。
- 注※4
-
ResponseのMedia Typeがjsonである場合はtrueを設定します。json以外の場合はプロパティを省略します（=false）。
Path Item内の各オペレーションに定義されているResponseに1つでもjsonのMedia Typeがあればtrueとなります。
- 注※5
-
RequestBodyのMedia Typeがjson，またはxmlである場合はtrueを設定します。json，またはxml以外の場合はプロパティを省略します（=false）。
Path Item内の各オペレーションに定義されているRequestBodyに1つでもjson，またはxmlのMedia Typeがあればtrueとなります。
この表に記載がないHTTP受付の設定についてはOpenAPI仕様書では定義できません。サービス定義XMLファイルのデフォルト値が採用されます。サービス定義XMLファイルについては，マニュアル「サービスプラットフォーム 開発ガイド 基本開発編」の「6. サービス定義のインポート・エクスポート」を参照してください。
(b) ビジネスプロセスとOpenAPI仕様書との対応
ビジネスプロセスとOpenAPI仕様書との対応を次の表に示します。
|
項番 |
ビジネスプロセスの設定 |
OpenAPI仕様書のフィールド |
サービス定義XML |
||||
|---|---|---|---|---|---|---|---|
|
タグ |
設定値 |
フィールドが定義されていない場合の設定値 |
|||||
|
1 |
ビジネスプロセス名 |
Operation#x-csd-business-process-name |
/service-definition/business-process/overview/name |
Operation#x-csd-business-process-nameに設定した名称 |
デフォルトのビジネスプロセス名を設定します。 |
||
|
2 |
サービスID |
Operation#x-csd-business-process-id |
/service-definition/business-process/overview/service-id |
Operation#x-csd-business-process-idに設定した名称 |
デフォルトのIDを設定します。 |
||
|
3 |
変数定義 |
要求電文ヘッダ |
変数名 |
Operation#x-csd-request-header-variable-name |
/service-definition/business-process/variables/global/variable/name |
Operation#x-csd-request-header-variable-nameに設定した名称 |
デフォルトの変数名を設定します。 |
|
4 |
種別 |
− |
/service-definition/business-process/variables/global/variable/type |
XML |
− |
||
|
5 |
電文フォーマット |
− |
/service-definition/business-process/variables/global/variable/file-path |
<サービスプラットフォームのインストールディレクトリ>/CSC/custom-reception/http/schema/urecp_http_header_request.xsd |
− |
||
|
6 |
要求電文ボディ |
変数名 |
Media Type#x-csd-variable-name |
/service-definition/business-process/variables/global/variable/name |
Media Type#x-csd-variable-nameに設定した名称 |
デフォルトの変数名を設定します。 |
|
|
7 |
種別 |
− |
/service-definition/business-process/variables/global/variable/type |
XML |
− |
||
|
8 |
電文フォーマット |
Request Body#content |
/service-definition/business-process/variables/global/variable/file-path |
XSDのファイルパス |
− |
||
|
Media Type#schema |
|||||||
|
9 |
応答電文ヘッダ |
変数名 |
Operation#x-csd-response-header-variable-name |
/service-definition/business-process/variables/global/variable/name |
Operation#x-csd-response-header-variable-nameに設定した名称 |
デフォルトの変数名を設定します。 |
|
|
10 |
種別 |
− |
/service-definition/business-process/variables/global/variable/type |
XML |
− |
||
|
11 |
電文フォーマット |
− |
/service-definition/business-process/variables/global/variable/file-path |
<サービスプラットフォームのインストールディレクトリ>/CSC/custom-reception/http/schema/urecp_http_header_response.xsd |
− |
||
|
12 |
応答電文ボディ |
変数名 |
Media Type#x-csd-variable-name |
/service-definition/business-process/variables/global/variable/name |
Media Type#x-csd-variable-nameに設定した名称 |
デフォルトの変数名を設定します。 |
|
|
13 |
種別 |
− |
/service-definition/business-process/variables/global/variable/type |
XML |
− |
||
|
14 |
電文フォーマット |
Response#content |
/service-definition/business-process/variables/global/variable/file-path |
XSDのファイルパス |
− |
||
|
Media Type#schema |
|||||||
|
15 |
受付アクティビティ |
アクティビティ名 |
Operation#x-csd-receive-activity-name |
/service-definition/business-process/activities/global/main-sequence/receive-activity/activity-name |
Operation#x-csd-receive-activity-nameに設定した名称 |
デフォルトの変数名を設定します。 |
|
|
16 |
オペレーション名 |
− |
/service-definition/business-process/activities/global/main-sequence/receive-activity/operation-name |
Operationに定義したHTTPメソッド名 |
− |
||
|
17 |
ボディ割当変数 |
− |
/service-definition/business-process/activities/global/main-sequence/receive-activity/body-variable-name-ref |
項番6の変数 |
− |
||
|
18 |
ヘッダ割当変数 |
割当変数 |
− |
/service-definition/business-process/activities/global/main-sequence/receive-activity/headers/header/variable-name-ref |
項番3の変数 |
− |
|
|
ルート要素 |
− |
/service-definition/business-process/activities/global/main-sequence/receive-activity/headers/header/root-element-name |
http-header-request |
− |
|||
|
19 |
応答アクティビティ |
アクティビティ名 |
Operation#x-csd-reply-activity-name |
/service-definition/business-process/activities/global/main-sequence/reply-activity/activity-name |
Operation#x-csd-reply-activity-nameに設定した名称 |
デフォルトの変数名を設定します。 |
|
|
20 |
オペレーション名 |
− |
/service-definition/business-process/activities/global/main-sequence/reply-activity/operation-name |
Operationに定義したHTTPメソッド名 |
− |
||
|
21 |
ボディ割当変数※ |
− |
/service-definition/business-process/activities/global/main-sequence/reply-activity/body-variable-name-ref |
項番12の変数 |
− |
||
|
22 |
ヘッダ割当変数 |
割当変数 |
− |
/service-definition/business-process/activities/global/main-sequence/reply-activity/headers/header/variable-name-ref |
項番9の変数 |
− |
|
|
ルート要素 |
− |
/service-definition/business-process/activities/global/main-sequence/reply-activity/headers/header/root-element-name |
http-header-response |
− |
|||
（凡例）−：該当しません。
- 注※
-
ResponseがResponses内で複数定義されていた場合は要素を省略します。
(4) 設定項目の命名規則
受付名やビジネスプロセス名などの設定項目は，OpenAPI仕様書にCSD独自のフィールドを定義することで設定できます。CSD独自フィールドの設定値は，変換時に検証され，エラーになった場合，またはCSD独自フィールドが定義されていない場合は，規則に従ってデフォルト値が設定されます。
CSD独自フィールドと設定項目の対応を次に示します。
|
HCSCコンポーネントの設定項目 |
CSD独自フィールド |
デフォルト値 |
デフォルト値の設定例 |
|---|---|---|---|
|
受付名 |
Path Item#x-csd-reception-name |
rcp<連番>※1 |
rcp1, rcp2, rcp3, … |
|
受付ID |
Path Item#x-csd-reception-id |
<連番>※1※2 |
1, 2, 3, … |
|
ビジネスプロセス名 |
Operation#x-csd-business-process-name |
bp<連番>※1_<HTTPメソッド名> |
bp1_get, bp2_put, … |
|
サービスID |
Operation#x-csd-business-process-id |
<連番>※1※2 |
1, 2, 3, … |
|
受付アクティビティ名※3 |
Operation#x-csd-receive-activity-name |
receive_activity |
− |
|
応答アクティビティ名※3 |
Operation#x-csd-reply-activity-name |
reply_activity |
− |
|
変数名※4 |
|
|
− |
（凡例）−：該当しない。
- 注※1
-
連番は変換順に1から1つずつ繰り上がります。連番を付与したあとの名称が重複する場合は番号をさらに1つ繰り上げます。
- 注※2
-
受付IDとサービスIDは共通の連番を使用し，重複しないように設定されます。
![[図データ]](GRAPHICS/ZC021314.GIF)
- 注※3
-
デフォルトの名称がすでに使用されている場合は，連番を付与します。
（例）receive_activity1
- 注※4
-
デフォルトの名称がすでに使用されている場合は，アンダーバーと連番を付与します。
（例）http_body_response_200_1
(5) OpenAPI仕様書の変換
OpenAPI仕様書をHCSCコンポーネントに変換するには，cscoas2servicedefコマンドにOpenAPI仕様書のファイルパスや出力先ディレクトリなどの指定が必要です。
cscoas2servicedefコマンドの詳細については，マニュアル「サービスプラットフォーム リファレンス」の「cscoas2servicedef（OpenAPI仕様書をHCSCコンポーネントの定義に変換）」を参照してください。
(6) OpenAPI仕様書の変換時の注意事項
-
cscoas2servicedefコマンドに指定した出力先ディレクトリに同名のファイルがある場合は，上書きされます。
-
cscoas2servicedefコマンドに指定した出力先ディレクトリがない場合は，新規にディレクトリを作成し，ファイルを出力します。出力先ディレクトリと同名のファイルがあった場合はエラーとなります。
-
入力ファイルに使用できる文字コードはUTF-8だけです。UTF-8以外の文字コードのファイルが入力された場合の動作は保証しません。各定義ファイルの出力時に使用する文字コードもUTF-8となります。
-
OpenAPI仕様書内に記述されたOpenAPI Specificationのバージョンが3.0以降でない場合，およびフィールドが省略されていた場合はエラーとなります。
-
XML Schemaファイルの生成では，Schemaオブジェクト内の次の情報を利用します。
-
example（データ例）
-
default（デフォルト値）
-
enum（値の列挙型）
これらのフィールドがSchemaオブジェクトのtypeやpropertiesフィールドなどに沿って定義されていない場合は，SchemaオブジェクトどおりのXML Schemaが生成されないことがあります。
-
-
変換結果のファイル名やディレクトリ名として使用するフィールドにはWindowsのファイル名として利用できない文字および名称は指定できません。指定した場合の動作は保証されません。
-
$refを使用する場合，正しい参照先を指定してください。参照が解決できなかったときは，正しく変換されない場合があります。
-
XML Schemaファイルを生成する場合に，OpenAPI仕様書インポート機能で対応するSchemaオブジェクトのフィールドを次に示します。
-
type
-
items
-
properties
-
format
-
enum
-
default
-
example
-
xml
-
-
Media Typeがjsonの場合に生成されるXML Schemaファイルは，スキーマ内に定義される要素がjsonのオブジェクト名の昇順にソートされます。
-
受付名などを設定するためのCSDの独自フィールドの値は，文字列で指定してください。
-
XML Schemaの生成で，Schemaオブジェクトにitemsフィールドが定義されている場合は，typeフィールドの値に関係なく，arrayとして扱われます。
-
XML Schemaの生成で，XMLオブジェクトのnamespaceフィールドはルート要素にだけ指定できます。また，namespaceフィールドを指定する場合は，prefixフィールドの指定も必要です。
-
XML Schemaの生成では，XMLオブジェクトのwrappedフィールドは指定できません。
-
XML Schemaの生成で，次のときはXML Schemaが生成されません。
-
Media Typeがjsonの場合で，最上位に定義されているSchemaオブジェクトのtypeフィールドがobjectまたはarrayでないとき
-
Media Typeがxmlの場合で，最上位に定義されているSchemaオブジェクトのtypeフィールドがobjectでないとき
-