![[17.0.0.1 and later]](../ng_v17001plus.gif)
Swagger 2.0 文書フィールドの上書き
server.xml ファイルで swaggerDefinition 属性を使用して、 /docs エンドポイントおよび /explorer エンドポイントによって提供される Swagger 2.0 文書内の一部のフィールドを上書きします。
始める前に
最初に server.xml ファイルに apiDiscovery-1.0 フィーチャーを追加し、その後、Liberty REST エンドポイントで Swagger 2.0 文書を公開する必要があります。『Liberty サーバー上の REST API 資料のディスカバー』にある手順のステップ 1 と 2 を実行してください。
手順
- swaggerDefinition スニペットを作成して、上書きするフィールドが含まれている JSON または YAML の Swagger スニペットを指定します。info フィールド、
schemes フィールド、consumes フィールド、produces フィールド、および externalDocs フィールドを上書きできます。
例えば、以下の swaggerDefinition スニペットは、/explorer HTML ページの description フィールド、title フィールド、およびその他の info フィールドを変更します。
{ "swagger" : "2.0", "info":{ "description":"My description", "version":"1.0.0", "title":"My title", "x-ibm-css":"${server.config.dir}/css/acme-banner.css", "termsOfService":"http://swagger.io/terms/", "contact":{ "email":"apiteam@swagger.io" }, "license":{ "name":"Apache 2.0", "url":"http://www.apache.org/licenses/LICENSE-2.0.html" } } }
title および description の値に加えて、/explorer HTML ページのバナーおよびロゴ HTML エレメントをカスタマイズできます。 swaggerDefinition スニペットの info フィールド内で、バナーおよびロゴの部分をオーバーライドする CSS ファイルの場所を指すように x-ibm-css フィールドを指定できます。この CSS ファイルのフォーマット要件は以下のとおりです。
- この CSS ファイルは .swagger-section #header CSS エレメントを指定する必要があります。
- 新しいロゴは images/custom-logo.png フォーマットを使用する必要があります。 ここで、custom-logo はイメージ・ファイルの名前です。ロゴ・ファイルのパスを CSS ファイルに対する相対パスにします。
- この CSS ファイルは background-image プロパティーが url(images/custom-logo.png) 値に設定されたカスタム・ロゴ・イメージを参照する必要があります。
- ロゴ・ファイルは PNG フォーマットでなければなりません。
上書きする CSS ファイルの例を以下に示します。
.swagger-section #header { background-image: url(images/custom-logo.png); background-repeat: no-repeat; background-color: lightslategray; background-position-x: 28px; padding-top: 20px; padding-right: 0px; padding-bottom: 20px; padding-left: 5px; height: 75px; }
- server.xml ファイルに swaggerDefinition 属性を追加します。
swaggerDefinition 属性の値は以下のいずれかにできます。
- ファイル拡張子 .json または .yaml で終わる、ローカル・ファイルのパス。このパスには、ランタイム・ディレクトリーと関連付けられた Liberty 変数を組み込むことができます。以下に例を示します。
<apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
- http または https で始まる、Swagger スニペットの絶対 URL。以下に例を示します。
<apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
- サーバーにデプロイされたアプリケーションのコンテキスト・ルート。コンテキスト・ルートはスラッシュ (/) で始まります。以下に例を示します。
<apiDiscovery swaggerDefinition="/myApplication" />
Liberty サーバーにデプロイされた Web アプリケーションが 1 つの場合、ユーザー・エクスペリエンスを向上させるため、その Web アプリケーションの Swagger 文書は swaggerDefinition スニペットとして使用されます。 server.xml 内に swaggerDefinition 属性が定義されていなくても、/docs エンドポイントで提供される Swagger 文書では、そのアプリケーションからのすべてのフィールドが上書きされます。2 つ目の Web アプリケーションがサーバーにデプロイされると、単一のアプリケーションでの最適化によって影響を受けていたすべてのフィールドはデフォルト値に戻ります。
- ファイル拡張子 .json または .yaml で終わる、ローカル・ファイルのパス。このパスには、ランタイム・ディレクトリーと関連付けられた Liberty 変数を組み込むことができます。以下に例を示します。

ファイル名: twlp_api_discovery_swagger_def.html