[17.0.0.1 and later]

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 を実行してください。

手順

  1. 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;
    }
  2. 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 アプリケーションがサーバーにデプロイされると、単一のアプリケーションでの最適化によって影響を受けていたすべてのフィールドはデフォルト値に戻ります。


トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_api_discovery_swagger_def.html