OpenAPI を使用した REST API 資料の生成

<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>

API がプライベートなままになるよう指定することができます。 管理用に使用される API は通常はプライベートのままにされます。 プライベート API は、保護のためにパスワードを使用し、/ibm/api/docs リソース内に文書化されます。 このリソースは、すべてのプライベート API およびすべてのパブリック API を文書化します。

次の 2 つの方法で、Web アプリケーションのプライベート API を指定できます。

• サーバー構成内で、public 属性を false に設定して webModuleDoc を使用します。
  1. openapi エレメントを追加し、その enablePrivateURL ブール属性を true に設定します。
  2. Web アプリケーションごとに 1 つの webModuleDoc サブエレメントを追加し、その public ブール属性を、パブリック API の場合は true に、プライベート API の場合は false に設定します。

  次の例では、airlines アプリケーション OpenAPI を可視化し、airlinesAdmin アプリケーション OpenAPI の公開を無効にしています。

  
  <openapi enablePrivateURL="true">
    <webModuleDoc contextRoot="/airlines" public="true" />
    <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
  </openapi>
  

  デフォルトでは、webModuleDoc の public 属性は true に設定されます。 この構成が必要なのは、プライベートなままにしたいアプリケーションを使用不可にする場合のみです。

• API 記述でベンダー拡張キーワードを使用して、API がプライベートであることを指定します。
  1. サーバー構成に openapi エレメントを追加し、その enablePrivateURL ブール属性を true に設定します。
  2. x-ibm-private: true キーワードと値を、API 記述文書 META-INF/openapi.yaml ファイル、または、別のサポートされるフォーマットのファイル内に置きます。 この値は API のデフォルトの可視性をオーバーライドし、webModuleDoc 項目はこの値をオーバーライドできます。

contextRoot 属性を使用して、非表示または表示する Web モジュールを特定します。 次に、enabled 属性を false に変更して、OpenAPI 文書で Web モジュールを非表示にします。 enabled 属性のデフォルト値は true です。 次の例では、airlines モジュールは OpenAPI 文書に表示されるように構成され、airlinesAdmin モジュールは非表示にされています。

<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>

<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>