IBM API Connectの製品とAPIにx-embedded-doc を使って、ドキュメントを追加する

IBM API Connectでは、APIの仕様を公開するために、開発者ポータルという機能があります。
開発者ポータルでは、APIの概要（APIのタイプ、プロトコル、エンドポイント、セキュリティー）や、アクセスするURLやメソッド（GET,POST,PUT,DELETE)及び、プロパティ定義などが参照できるようになっています。

以下は、開発者ポータルのAPI仕様の画面

この開発者ポータルのAPIのドキュメントに、x-embedded-docを利用してドキュメントを追加することが可能になっています。
API ConnectでAPIを定義すると、API Swaggerドキュメントができます。このAPI Swaggerドキュメントに追加のドキュメンテーション・ページを組み込むことが可能です。
ページの html コンテンツの Base64 エンコードされたストリング、またはマークダウン・ストリングです。
これらのページは、左側のナビゲーションで、その製品または API の概要の下かつパスの上に表示されます。

製品および API の組み込みドキュメンテーション

製品または API の仕様に追加の x-embedded-doc オブジェクトを指定することで、個々の製品や API にドキュメントを組み込むことができます。

フィールド名	タイプ	説明
名前	string	(必須) 組み込みドキュメントの名前
タイトル	string	(必須) 組み込みドキュメントの表示タイトル
形式	string	(オプション) 組み込みドキュメントのコンテンツ値の形式。 値はb64htmlまたはmdです。 デフォルト値は md です。
コンテンツ	string	ページの Base64 エンコードされた html、またはマークダウン・ストリング。
資料	x-embedded-doc	追加の組み込みドキュメンテーション。 親にコンテンツが指定されていない場合は、最初の子がコンテンツとして表示されます。

x-embedded-docの使用例

例として、下記のようなx-embedded-docをGlobalWeatherというAPIに組み込んでみます。

x-embedded-doc:
  - name: 紹介
    title: 紹介
    format: md
    content: '# マークダウンで記述'
  - name: concepts
    title: Concepts
    format: md
    content: |-
      ## Overview
      #### Philosophy 
      API仕様に関する補足情報をMarkdown形式で記載できます。

      ***
      - 
      1. 番号   
        2. 番号   
      `backslash`  
      > 引用です<br> *引用です*
      >> **2つの引用です**
  - name: authentication
    title: Authentication
    docs:
      - name: auth_clientid_secret
        title: Obtaining a Client ID and Secret
        format: md
        content: '### Client IDとSecretを取得する方法を記載'
      - name: auth_bearertoken
        title: Getting and Using a Bearer Token
        format: md
        content: '#### Bearer Tokenの取得と使い方を記載'

API ManagerのAPI定義画面のソースに定義します

APIを公開します

開発者ポータルから確認します

開発者ポータルから、GlobalWeatherのAPIを開いてみると、左側に新しく情報が追加されていることがわかります。以下の三つの項目が追加されています。

• 紹介
• Concept
• Authentication
  • Obtaining a Client ID and Secret
  • Getting and Using a Bearer Token

以上のように、API Connectの開発者ポータルに追加のドキュメントを記載するには、x-embedded-docを使うことで簡単に公開することが可能です。