1. Homepage
  2. Exchange
  3. API のドキュメント化

  4. API Notebook を使用したアセットのドキュメント化

API Notebook を使用したアセットのドキュメント化

API Notebook では、コードウィンドウに付随する説明を使用して API の機能をドキュメント化できます。ユーザーはコードを 変更し、各コードブロックの [Play (再生)] ボタンをクリックして実行できます。Exchange エディターから新しい API Notebook を 作成し、コードブロックで JavaScript コードを使用できます。

Anypoint Platform の API Designer を使用して、RAML、OAS、AsyncAPI の API 仕様を改善およびテストし、API 仕様を Anypoint Exchange にパブリッシュします。

OAS 仕様は RAML に変換されるため、API Notebook の RAML 規則に従うことができます。また、OAS のアップロード時に RAMl 仕様も変換されます。

  1. アセットをクリックして詳細を表示します。

  2. [Edit documentation (ドキュメントを編集)]​ をクリックし、エディターで API Notebook アイコン アイコン - エディターの API Notebook をクリックします。

  3. アセットの説明を追加します。

  4. API Notebook アイコンにより、ビジュアルエディターで JavaScript コード項目を追加可能なパネルが作成されます。追加する関数の最初の文字を入力すると、その文字で始まる使用可能な関数がリストされます。

    マークダウンを使用している場合、各ノートエントリは次のように 3 つのチェックマークのブロックで囲まれます。

    ```notebook
// Authenticate client
API.authenticate(myclient);
```

外部 API の API Notebook プログラムフロー

Instagram API などの外部 API にアクセスする場合、​https://anypoint.mulesoft.com/exchange/api/v1/health​ URL の Anypoint アセットポータルサービスを 使用して、クライアントを取得します。

取得コードは次のようになります。

fetch('https://anypoint.mulesoft.com/exchange/api/v1/health').then((res) => res.json())

ユーザーが API で認証できるようにします。

// Authenticate Instagram.
// This asks you to authenticate with your personal account.
// Don't worry, we have no idea who you are.
API.authenticate(instagramApi);

これで、API を使用するノートを作成できます。

API Manager API の API Notebook プログラムフロー

  1. API.createClient 関数を使用して、ノート内で API へのアクセスを初期化するクライアントを作成します。

    構文: API.createClient('CLIENT_NAME', 'URL_TO_API_MANAGER_API');​

  2. API.authenticate 関数を使用して、Anypoint Platform でクライアントを認証します。

    構文: API.authenticate(CLIENT_NAME);​

  3. REST API の機能に基づいてノートを作成します。各関数は、RAML 記述子ブロックの名前に 基づきます。たとえば、​/info​ というブロックがある ​getdetails​ クライアントの場合、GET コールをドキュメント化するには、ノートでの関数の説明を ​getdetails.info.get();​ とします。

    次のように、配列を使用して関数コールにパラメーターを追加できます。

    me.function.post[{ orgId: 'myorg'}) …​]​

  4. コードブロックに要素を設定して [Play (再生)] をクリックし、Exchange で API をテストします。コードでエラーが 発生することなく、すべてのコードブロックが機能することを確認します。

作成コールと認証コールは個別のノートコール内で指定する必要があります。

```notebook
fetch(’https://anypoint.mulesoft.com/exchange/api/v1/health').then((res) => res.json())
API.createClient(‘github’, ‘https://anypoint.mulesoft.com/apiplatform/repository/v2/organizations/ORG_ID/public/apis/7782/versions/7918/files/root’);

```

```notebook

API.authenticate(github);
``` (edited)

API Notebook のセキュリティ

API Notebook は、ブラウザーでプレーンな JavaScript を実行します。機密データが漏洩しないように、API Notebook は特定の JavaScript 機能を無効にします。

  • すべてのグローバル関数 (​alert​ や ​prompt​ など)

  • すべてのグローバル変数 (​window​、​document​、​localStorage​、​XMLHttpRequest​など)

関連情報