|
|
WebOTX Manual V11.1 (第6版) 目次を表示 |
|
|
|
WebOTX Manual V11.1 (第6版) 目次を表示 |
MicroProfile OpenAPI はJAX-RSアプリケーションからOpenAPIドキュメントを作成する機能を提供します。また、OpenAPI v3仕様に準拠したJava API、および静的OpenAPIドキュメント機能(yaml, jsonに対応)を提供します。
本機能を用いることで、アプリケーション開発者はアプリケーションのAPIドキュメントを公開することができます。
※MicroProfile OpenAPIを使用していない既存のJAX-RSアプリケーションに対しても、基本的なOpenAPIドキュメントを生成することが可能です。
OpenAPIドキュメント公開のエンドポイントは/openapiです。
本製品では Eclipse MicroProfile OpenAPI V2.0をサポートしています。
詳細は以下を参照してください。
MicroProfile OpenAPI Specification V2.0
OpenAPIエンドポイントは、OpenAPIドキュメントにアクセスするためのルートURLです。
HTTP GETメソッドをサポートします。
例 http(s)://myHost:myPort/openapi
運用管理コマンド、または運用管理コンソールからOpenAPIエンドポイントの有効化・無効化を設定することが可能です。
設定変更後はドメインの再起動が必要となります。
本製品ではエディション毎にOpenAPIエンドポイント有効・無効の初期値が異なります。
各エディションのOpenAPIエンドポイント初期値は以下の通りです。
| エディション | OpenAPIエンドポイント 初期値 |
設定変更方法 |
|---|---|---|
| WebOTX Uber JAR | true (有効) |
OpenAPIエンドポイントを無効化する場合、Uber JAR生成ツールを使用し、pre-start-commands.confを配置します。 pre-start-commands.confに定義するコマンドは OpenAPIエンドポイントの無効化 を参照してください。 Uber JARのカスタマイズ方法は マイクロサービスプロファイルを使用したWebOTX Uber JARの作成 を参照してください。 |
Application Server Express for Container
|
false (無効) |
OpenAPIエンドポイントを有効化する場合、Dockerfileに以下の定義を追加して、コンテナイメージを再ビルドしてください。RUN /opt/WebOTX/bin/otxadmin --user admin --password adminadmin start-domain domain1 && \ /opt/WebOTX/bin/otxadmin --user admin --password adminadmin set server.microprofile.openapi-enabled=true && \ /opt/WebOTX/bin/otxadmin --user admin --password adminadmin stop-domain domain1コマンドの詳細は OpenAPIエンドポイントの有効化 を参照してください。 コンテナイメージのカスタマイズ方法は 公開イメージの利用 を参照してください。 |
Application Server Standard for Container
|
||
| WebOTX Express | false (無効) |
OpenAPIエンドポイントを有効化する場合、運用管理コマンド、または運用管理コンソールを使用します。 有効化の詳細は OpenAPIエンドポイントの有効化 を参照してください。 |
| WebOTX Standard |
OpenAPIエンドポイントを使用する場合、下記のコマンドを使用し有効化を行います。
otxadmin > set server.microprofile.openapi-enabled=true
運用管理コンソールから変更する場合、[アプリケーションサーバ] > [マイクロプロファイル] > [OpenAPI有効化] の値を変更してください。
OpenAPIエンドポイントを使用しない場合、下記のコマンドを使用し無効化を行います。
otxadmin > set server.microprofile.openapi-enabled=false
現在の設定内容を確認する場合は下記のコマンドを実行してください。
otxadmin > get server.microprofile.openapi-enabled
本製品では複数のアプリケーションが配備された場合、アプリケーション名を辞書順にソートし、その第一位のアプリケーションに対してOpenAPIドキュメントを生成します。
またアプリケーションの配備解除・アプリケーションの停止を実行した場合も、その都度ソートを行い、対象となるOpenAPIドキュメントを生成し直します。
本製品のWebサーバではCORS設定(Cross-Origin Resource Sharing)の既定値は無効になっています。
Webサーバの種類毎に変更方法が異なりますので、ご使用の環境に応じて必要な設定を行ってください。
設定変更後はドメインの再起動が必要となります。
| エディション | Webサーバの種類（既定値） | CORS設定変更方法 |
|---|---|---|
| WebOTX Uber JAR | 内蔵Webサーバ |
Uber JAR生成ツールを使用し、default-web.xmlの設定変更を行います。 設定内容の詳細は 内蔵WebサーバのCORS設定手順 を参照してください。 |
Application Server Express for Container
|
内蔵Webサーバ |
Dockerfileを使用し、default-web.xmlの設定変更を行います。 設定内容の詳細は 内蔵WebサーバのCORS設定手順 を参照してください。 |
Application Server Standard for Container
|
Webサーバ |
Dockerfileを使用し、httpd.confの設定変更を行います。 設定内容の詳細は WebサーバのCORS設定手順 を参照してください。 |
| WebOTX Express | インストール時に任意選択。 Webサーバ or 内蔵Webサーバ |
OpenAPIエンドポイントを有効化する場合、運用管理コマンド、または運用管理コンソールを使用します。 有効化の詳細は 内蔵WebサーバのCORS設定手順 、 WebサーバのCORS設定手順 を参照してください。 |
| WebOTX Standard |
default-web.xmlの設定
default-web.xmlの設定例
ご利用の環境に応じて、<WebOTXインストールルート>/domains/<ドメイン名>/config/default-web.xmlの赤字部分の定義を追加します。
<!-- For OpenAPI Endpoint -->
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value> （環境に応じたorigin情報の定義を追加）</param-value>
</init-param>
..snip..
</filter>
..snip..
<!-- For OpenAPI Endpoint -->
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/openapi</url-pattern>
<url-pattern> /"アプリケーション内でCORSフィルタ定義が必要なリソースパス" を全て追加 </url-pattern>
</filter-mapping>
Memo
本製品では <url-pattern>の /* 指定は未サポートです。セキュリティ面でも /* 指定は推奨致しませんので、ご注意ください。
ドメインを再起動することで、設定が反映されます。
httpd.conf、およびdefault-web.xmlの設定
httpd.confの設定例
ご利用の環境に応じて、<WeboOTXインストールルート>/domains/<ドメイン名>/config/WebServer/httpd.conf に赤字部分の定義を追加します。
...
LoadModule headers_module "<WeboOTXインストールルート文字列>/WebServer24/modules/mod_headers.so"
（コメントアウトを解除）
...
Header set Access-Control-Allow-Origin '(環境に応じたorigin情報)'
...
default-web.xmlの設定例
ご利用の環境に応じて、<WeboOTXインストールルート>/domains/<ドメイン名>/config/default-web.xmlの赤字部分の定義を追加します。
<!-- For OpenAPI Endpoint -->
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
..snip..
ドメインを再起動することで、設定が反映されます。
MicroProfile OpenAPIのドキュメント作成は以下の順序で作成されます。
| 処理 ステップ |
概要 | 説明 |
|---|---|---|
| １ | 設定情報の読み込み |
microprofile-config.propertiesの読み込み microprofile-config.propertiesについては「その他の設定項目」を参照してください。 |
| ２ | OASModelReaderの起動 |
microprofile-config.propertiesのmp.openapi.model.readerに指定されている場合、起動します。 OASModelReaderインタフェース実装をもとにOpenAPIドキュメントを作成します。 mp.openapi.model.readerが指定されていない場合、スキップします。 |
| ３ | 静的ファイルの読み込み |
静的ファイルからOpenAPIドキュメントを作成し、前の処理ステップで作成されているOpenAPIドキュメントと 競合する要素が存在する場合は上書します。また、存在しない場合は追加されます。 静的ファイルが存在しない場合、スキップします。 |
| ４ | OpenAPIアノテーションの読み込み |
ユーザ作成アプリケーション内に定義されたOpenAPIアノテーションからOpenAPIドキュメントを作成します。 前の処理ステップで作成されているOpenAPIドキュメントと競合する要素が存在する場合は上書きします。 また、存在しない場合は追加されます。 mp.openapi.scan.disableにtrueが設定されている場合、スキップします。 なお、RegisterRestClientアノテーション（MicroProfile Rest Clientのアノテーション）が付与されたメソッドは除外します。 |
| ５ | OASFilterの起動 |
microprofile-config.propertiesのmp.openapi.filterに指定されている場合、起動します。 前の処理ステップで作成されているOpenAPIドキュメントにフィルタリングを行います。 mp.openapi.filterが指定されていない場合、スキップします。 |
| ６ | Default OpenAPIドキュメントの生成 |
前の処理ステップでOpenAPIドキュメントが作成されていない場合に作成します。 |
MicroProfile OpenAPIドキュメント作成の概要フロー
Default OpenAPIドキュメントを次に示します。
openapi: 3.0.3
info:
title: Generated API
version: "1.0"
servers:
- url: http://myHost:myPort/openapi-sample-default
description: Default Server.
- url: https://myHost:myPort/openapi-sample-default
description: Default Server.
paths: {}
Server情報（赤）は、実行環境に合わせて出力しています。
その他の情報（青）は、Default OpenAPIドキュメントを出力しています。
MicroProfile OpenAPI の設定項目は、[ リファレンス > 設定 > マイクロサービスアプリケーション > MicroProfile OpenAPI ] を参照してください。
MicroProfile OpenAPI は次のアノテーションを提供します。
各アノテーションの詳細は MicroProfile OpenAPI API 2.0 API を参照してください。
| コンポーネント | アノテーション名 | 説明 |
|---|---|---|
| openapi | @Components | OpenAPI仕様の再利用可能なオブジェクトを定義する。 |
| @ExternalDocumentation | 拡張ドキュメントの外部リソースを定義する。 | |
| @OpenAPIDefinition | OpenAPI定義の一般的なメタデータを定義する。 | |
| @Operation | 特定のパスに対する操作または通常はHTTPメソッドを定義する。 | |
| callbacks | @Callback | コールバックURLを定義する。 |
| @Callbacks | コールバックURLの配列を定義する。 | |
| @CallbackOperation | コールバックURLの配列を定義する。 | |
| extentions | @Extension | OpenAPI定義に追加する拡張機能を定義する。 |
| @Extensions | OpenAPI定義に追加する拡張機能の配列を定義する。 | |
| header | @Header | HTTPヘッダーを定義する。 |
| info | @Contact | 公開されたAPIの連絡先情報を設定する。 |
| @Info | APIに関するメタデータを定義する。 | |
| @License | 公開されたAPIのライセンス情報を定義する。 | |
| link | @Link | リンク先を設定する。 |
| @LinkParameter | リンクされた操作に渡すパラメータを定義する。 | |
| media | @Content | 特定のメディアタイプのスキーマと例を定義する。 |
| @DiscriminatorMapping | ペイロード値を特定のスキーマに定義する。 | |
| @ExampleObject | 特定のコンテンツ例を定義する。 | |
| @Encoding | スキーマオブジェクトに適用される単一のエンコーディングを定義する。 | |
| @Schema | 入力と出力のデータ型を定義する。 | |
| @SchemaProperty | Schemaアノテーションの入れ子となる入力と出力のデータ型を定義する。 | |
| parameter | @Parameter | 操作パラメータを定義する。 |
| @Parameters | 入力パラメータを定義する。 | |
| @RequestBody | 単一のリクエスト本文を定義する。 | |
| @RequestBodySchema | RequestBodyアノテーションのスキーマを短縮表現で定義する。 | |
| responses | @APIResponse | OpenAPI操作に対応した単一のHTTP応答を定義する。 |
| @APIResponses | OpenAPI操作に対応した複数のHTTP応答を定義する。 | |
| @APIResponseSchema | APIResponseアノテーションのスキーマを短縮表現で定義する。 | |
| security | @OAuthFlow | サポートされるOAuthフローの構成の詳細を定義する。 |
| @OAuthFlows | サポートされているOAuthフローを定義する。 | |
| @OAuthScope | OAuthスコープを定義する。 | |
| @SecurityRequirement | 操作のセキュリティ要件を定義する。 | |
| @SecurityRequirements | 複数の操作のセキュリティ要件を定義する。 | |
| @SecurityRequirementsSet | 複数のセキュリティ要件の配列を定義する。 | |
| @SecurityScheme | 操作で使用できるセキュリティスキームを定義する。 | |
| @SecuritySchemes | 操作で使用されるサーバーを定義する。 | |
| server | @Server | 操作で使用されるサーバーを定義する。 |
| @Servers | 複数のサーバーを定義する。 | |
| @ServerVariable | サーバーURLテンプレート置換用のサーバー変数を定義する。 | |
| tags | @Tag | APIエンドポイントのタグを定義する。 |
| @Tags | 複数のタグを設定する。 |
OpenAPIアノテーションの記述例を下記に示します。
(サンプルプロジェクト openapi-sample.zip)
package sample;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
@Path("/hello")
public class SampleTestResource {
@GET
@Produces(MediaType.APPLICATION_JSON)
@APIResponses(
value = {
@APIResponse(responseCode = "404", description = "not found"),
@APIResponse(responseCode = "200", description = "Hello Sample")})
@Operation(summary = "Sample GET Hello")
public Response hello() {
return Response.ok("Hello Sample").build();
}
@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("/{id}")
@APIResponse(responseCode = "200", description = "User")
@APIResponse(responseCode = "400", description = "bad request")
@APIResponse(responseCode = "404", description = "ID not found")
@Operation(summary = "Sample GET",
description = "This method returns 400 if less than 0 and 404 if ID 100 more.")
public Response getId(@PathParam("id") int id) {
if (id < 0) {
return Response.status(400).build();
} else if (id > 100) {
return Response.status(404).build();
}
return Response.ok("UserID :" + id).build();
}
}
その他、OpenAPIアノテーションの記述例については、MicroProfile OpenAPI Specification V2.0 を参照してください。
MicroProfile OpenAPI はwarファイル内の、完全、または部分的な静的OpenAPIドキュメントを読み込むことができます。
対応するドキュメントのフォーマット及び、読込順序の優先度は以下の通りです。
複数の静的OpenAPIドキュメントを配置した場合、一番優先度の高いファイルが読み込まれます。
| 優先順位 | ファイル名（フォーマット） | warファイル内格納ディレクトリ |
|---|---|---|
| 1 | openapi.yaml (YAML) | META-INF/配下 |
| 2 | openapi.yaml (YAML) | WEB-INF/classes/META-INF/配下 |
| 3 | openapi.yml (YAML) | META-INF/配下 |
| 4 | openapi.yml (YAML) | WEB-INF/classes/META-INF/配下 |
| 5 | openapi.json (JSON) | META-INF/配下 |
| 6 | openapi.json (JSON) | WEB-INF/classes/META-INF/配下 |
OpenAPIドキュメント仕様の詳細は OpenAPI Specification V3.0 を参照してください。
静的ファイル (openapi.yaml) の記述例を下記に示します。
(サンプルプロジェクト openapi-sample-static.zip)
※このサンプルは、mp.openapi.scan.disableにtrueを設定しています。
openapi: 3.0.3
info:
title: Sample Staticfile Application
version: 1.0.0
paths:
/api/sampletest/samplestatic:
get:
operationId: static openapi file
/api/hello/{id}:
get:
responses:
"200":
description: successful operation
content:
text/plain:
schema:
discriminator:
propertyName: id
mapping:
"1": '#/components/schemas/hello'
"2": '#/components/schemas/hithere'
"3": '#/components/schemas/whatsup'
falseに指定した場合は、OpenAPIアノテーション、フィルタ機能によってOpenAPIドキュメントが拡張、上書きされます。
Memo
完全なOpenAPIドキュメントの静的ファイルを使用する場合、microprofile-config.propertiesファイルに、mp.openapi.scan.disableを定義する必要があります。
定義値は、mp.openapi.scan.disableにtrueを指定します。
mp.openapi.scan.disable=true
サンプルプロジェクトの実行結果を次に示します。
openapi: 3.0.3
info:
title: Sample Staticfile Application
version: 1.0.0
servers:
- url: http://myHost:myPort/openapi-sample-static
description: Default Server.
- url: https://myHost:myPort/openapi-sample-static
description: Default Server.
paths:
/api/sampletest/samplestatic:
get:
operationId: static openapi file
/api/hello/{id}:
get:
responses:
"200":
description: successful operation
content:
text/plain:
schema:
discriminator:
propertyName: id
mapping:
"1": '#/components/schemas/hello'
"2": '#/components/schemas/hithere'
"3": '#/components/schemas/whatsup'
Server情報（赤）は、実行環境に合わせて出力しています。
その他の情報（青）は、静的ファイル (openapi.yaml) で指定した情報を出力しています。
MicroProfile OpenAPI はOASModelReaderインタフェースを使用する事で、POJO形式で完全、または部分的なOpenAPIドキュメントを生成することができます。
プログラミングモデル機能の詳細は Eclipse MicroProfile OpenAPI Programming model を参照してください。
サンプルとして、プログラミングモデル機能を使用した実装例を次に示します。
(サンプルプロジェクト openapi-sample-reader.zip)
※このサンプルは、mp.openapi.scan.disableにtrueを設定しています。
public class SampleTestReader implements OASModelReader {
public OpenAPI buildModel() {
OpenAPI oas = OASFactory.createObject(OpenAPI.class)
.info(OASFactory.createObject(Info.class)
.title("Sample OASModelReader").version("1.0"))
.paths(OASFactory.createObject(Paths.class)
.addPathItem("/api/sampletest/samplereader", OASFactory.createObject(PathItem.class)
.GET(OASFactory.createObject(Operation.class).operationId("sample test reader")));
oas.setOpenapi("3.0.3");
return oas;
}
}
falseに指定した場合は、静的ファイル、OpenAPIアノテーション、フィルタ機能によってOpenAPIドキュメントが拡張、更新されます。
Memo
完全なOpenAPIドキュメントを生成するプログラミングモデル機能を使用する場合、microprofile-config.propertiesファイルに、mp.openapi.scan.disableを定義する必要があります。
定義値は、mp.openapi.scan.disableにtrueを指定します。
mp.openapi.scan.disable=true
Memo
プログラミングモデル機能を使用する場合には、このOASModelReaderインタフェースの実装を作成し microprofile-config.propertiesファイルに、mp.openapi.model.readerを定義します。
定義値は、mp.openapi.model.readerに実装したクラスの完全修飾名を指定します。
mp.openapi.model.reader=sample.SampleTestReader
サンプルプロジェクトの実行結果を次に示します。
openapi: 3.0.3
info:
title: Sample OASModelReader
version: "1.0"
servers:
- url: http://myHost:myPort/openapi-sample-reader
description: Default Server.
- url: https://myHost:myPort/openapi-sample-reader
description: Default Server.
paths:
/api/sampletest/samplereader:
get:
operationId: sample test reader
Server情報（赤）は、実行環境に合わせて出力しています。
その他の情報（青）は、OASModelReaderインタフェースの実装部分で指定した情報を出力しています。
MicroProfile OpenAPI はOASFilterインタフェースを使用する事で、定義済みOpenAPIドキュメントの要素を上書きすることができます。
フィルタ機能の詳細は Eclipse MicroProfile OpenAPI Filter を参照してください。
フィルタ機能には、１３のフィルターメソッドがあります。
filterPathItem(PathItem pathItem) filterOperation(Operation operation) filterParameter(Parameter parameter) filterHeader(Header header) filterRequestBody(RequestBody requestBody) filterAPIResponse(APIResponse apiResponse) filterSchema(Schema schema) filterSecurityScheme(SecurityScheme securityScheme) filterServer(Server server) filterTag(Tag tag) filterLink(Link link) filterCallback(Callback callback) filterOpenAPI(OpenAPI openAPI)
これらのメソッドにはすべて、要素をそのまま返すデフォルトの実装が定義されています。
サンプルとして、filterSchemaメソッドを使用した特定の要素を更新する実装例を次に示します。
(サンプルプロジェクト openapi-sample-filter.zip)
※このサンプルは、mp.openapi.scan.disableにfalseを設定しています。
@Override
public Schema filterSchema(Schema schema) {
if( schema.getDiscriminator() != null ) {
schema.getDiscriminator().setPropertyName("id");
schema.getDiscriminator().addMapping("1", "#/components/schemas/hello");
schema.getDiscriminator().addMapping("2", "#/components/schemas/hithere");
schema.getDiscriminator().addMapping("3", "#/components/schemas/whatsup");
}
return schema;
}
このサンプルは、SchemaにDiscriminatorMapping定義が存在する場合に、propertyNameに"id"、id値が１の場合に参照されるSchema名を"#/components/schemas/hello"に設定しています。
また、id値が２の場合に参照されるSchema名を"#/components/schemas/hithere"に設定、id値が３の場合に参照されるSchema名を"#/components/schemas/whatsup"に設定しています。
次に、filterOperationメソッドを使用した特定の要素を更新する実装例を次に示します。
@Override
public Operation filterOperation(Operation operation) {
if("Hello Sample Test".equals(operation.getOperationId())){
operation.setOperationId("Byebye Sample Test");
}
return operation;
}
このサンプルは、Operationに"Hello Sample Test"というOperationIdが存在する場合に、OperationIdを"Byebye Sample Test"に更新しています。
Memo
フィルタ機能を使用する場合には、このOASFilterインタフェースの実装を作成し microprofile-config.propertiesファイルに、mp.openapi.filterを定義します。
定義値は、mp.openapi.filterに実装したクラスの完全修飾名を指定します。
mp.openapi.filter=sample.SampleTestFilter
サンプルプロジェクトの実行結果を次に示します。
openapi: 3.0.3
info:
title: Sample staticfile Application
version: 1.0.0
servers:
- url: http://myHost:myPort/openapi-sample-filter
description: Default Server.
- url: https://myHost:myPort/openapi-sample-filter
description: Default Server.
paths:
/api/sampletest/samplereader:
get:
operationId: sample test reader
/api/sampletest/samplestatic:
get:
operationId: static openapi file
/api/hello/{id}:
get:
operationId: Byebye Sample Test
parameters:
- name: id
in: path
required: true
schema:
format: int32
type: integer
responses:
"200":
description: successful operation
content:
text/plain:
schema:
type: object
allOf:
- $ref: '#/components/schemas/hello'
- $ref: '#/components/schemas/hithere'
- $ref: '#/components/schemas/whatsup'
properties:
id:
format: int32
type: integer
status:
type: string
discriminator:
propertyName: id
mapping:
"1": '#/components/schemas/hello'
"2": '#/components/schemas/hithere'
"3": '#/components/schemas/whatsup'
components:
schemas:
hello:
type: object
properties:
id:
format: int32
type: integer
status:
type: string
hithere:
type: object
properties:
id:
format: int32
type: integer
status:
type: string
whatsup:
type: object
properties:
id:
format: int32
type: integer
status:
type: string
Server情報（赤）は、実行環境に合わせて出力しています。
Path情報（青）は、静的ファイル (openapi.yaml) で指定した情報を出力しています。
Path情報（緑）は、OASModelReaderインタフェースの実装部分で指定した情報を出力しています。
Path情報、Components情報（紫）は、OpenAPIアノテーション情報を出力しています。
Path情報（水色）は、フィルタ機能（filterOperationメソッド）を使用して出力しています。
Path情報（ピンク）は、フィルタ機能（filterSchemaメソッド）を使用して出力しています。
本製品のOpenAPIと外部ツールを利用した開発モデルのイメージは以下の通りです。
OpenAPIドキュメントの実装
OpenAPIドキュメントの作成方法は複数あります。アプリケーションの配備
OpenAPIドキュメントを実装したアプリケーションを本製品に配備します。
外部ツールからOpenAPIエンドポイント（/openapi）にアクセスする
OpenAPI対応の外部ツールからOpenAPIエンドポイントにアクセスします。各ツールの開発支援機能を利用することができます。
Swagger-UIはOpenAPIドキュメントをHTML型式で表示するツールです。
本製品のOpenAPIエンドポイント（/openapi）にSwagger-UIからアクセスすることで、MicroProfile OpenAPIによって生成されたOpenAPIドキュメントが自動的に解析されます。
また、Swagger-UIはOpenAPIドキュメントから読み取ったREST APIを実行する機能があります。本機能によりバックエンド側の動作仕様の確認が容易になる為、
クライアント側の開発支援に効果的なツールです。
詳細は Swagger-UI を参照してください。
OpenAPI GeneratorはOpenAPIドキュメントを解析し、クライアント側コード、およびサーバ側コードを自動生成するツールです。
生成できるコードは多種にわたります。クライアント側の開発支援や、本製品と接合する外部サーバのスタブサーバを生成する等、様々な用途で利用可能なツールです。
詳細は OpenAPI Generator を参照して下さい。
ここでは、MicroProfile OpenAPI のサンプルアプリケーションを実行する手順について、説明します。
各サンプルの内容と目的については各章をご参照ください。
(1) WebOTX Developer へのインポート
サンプルプロジェクトの zip ファイルを展開して、WebOTX Developer にインポートしてください。
(2) MicroProfile OpenAPI を利用する JAX-RS アプリケーションの作成
OpenAPI 関連の機能を利用して、JAX-RS アプリケーションを作成します。上述のサンプルプロジェクトを確認してください。
(3) プロジェクトのビルド
WebOTX Developer のメニュー「プロジェクト」で「自動的にビルド」がチェックされていない場合は、「プロジェクトのビルド」を選択し、ビルドを行います。
(4) warファイルのエクスポート
プロジェクトを右クリックして、「エクスポート」−「WAR ファイル」を選択します。
「Destination」で出力先のパスを指定し、「終了」ボタンをクリックします。
(5) JAX-RS アプリケーションの配備
対象の環境に合わせて、アプリケーションを配備します。
コンテナ環境の場合は、[ 構築・運用 > コンテナ型仮想化 ] を参考に、本サンプルアプリケーションを含めたコンテナイメージを作成して、コンテナを起動してください。
コンテナ環境でない場合は、[ 配備 > アプリケーション配備 > 配備・再配備・置換 > 配備・再配備 ] を参考に、配備してください。
例) エージェントプロセス上に配備する場合
otxadmin> deploy (エクスポート時に指定したWARファイル名).war
(6) OpenAPIエンドポイントにアクセス
ブラウザ等から、OpenAPIエンドポイントにアクセスします。接続先ホスト名、ポート番号は、環境に合わせて変更してください。
http://localhost:8080/openapi
OpenAPIの各機能により生成したOpenAPIドキュメントを返却します。