更新情報

2020/01/09: IBM CloudがIAMに対応したことに関係したのか、SwaggerHubでのAPI Connect連携方法が変わっていたので、情報追記しました。

はじめに

今年の初めくらいに、SwaggerHubで作成したAPI定義をIBM CloudのAPI Connectにデプロイできるようになりましたので、今更ですが以下を参考に試してみました。
https://swaggerhub.com/blog/swaggerhub-feature/ibm-api-connect-and-swagger/
https://www.youtube.com/watch?v=iUBTCk41Wa4

連携するメリット？

あまり洗い出せてないですが、今の理解はこんな感じです。
とりあえず私の今の理解では、もともとAPI ConnectユーザーだったらSwaggerHubから連携しなくても、API ConnectのAPIデザイナー画面を使ってOpen APIに則ったAPI定義ができるので、わざわざSwaggerHubからデプロイする理由が思いついてません。。SwaggerHubユーザーが高度なAPIゲートウェイと連携するためというものかなと考えています。
間違い・不足事項などありましたらご指摘いただければと思います。

SwaggerHubでできること
- Swagger文書をチーム開発できる（でも有償）
- Swagger Codegen対応
- ドキュメントの自動生成
IBM Cloud API Connectでできること
- Open APIベースのAPI定義作成
- 複数のAPIを組み合わせや非機能要件を満たすためのフローの開発（API定義の拡張）
- APIの運用管理
  - API利用状況の可視化
  - 公開から廃止に至るライフサイクル
- レート制限、認証基盤との連携などセキュリティ周りの強化
- API利用者向けのポータル公開

手順

前提

SwaggerHubのアカウント（無料枠を使用）
IBM Cloudのアカウントがあり組織作成済みで、API Connectサービスがデプロイ済みであること（無料のライト・プラン使用）

SwaggerHubでAPI定義

SwaggerHubにログインして、新規API作成
ここではテンプレートにすでに定義済みのサンプルを選択します。なお注意点としてOpen API 2.0（デフォルト）を選択します。3.0にはAPI Connectは2017/12/20時点、まだ対応していないため連携ができなくなります。
こんな感じです。

API Connectへデプロイ

~~プラグボタンをクリックして連携先を追加します。~~
~~API Connectを選択して追加します。~~
IBM Cloudのアカウント情報を入れます。ID/PWを入れてValidate Credentialsをクリックすると、組織を選択できるのでIBM Cloudに設定してある組織を選択してCreate & Executeします。

１. [新しい方法] IBM Cloudで外部連携に必要なAPI Keyを取得しておきます。

Manager => Access(IAM) => IBM Cloud API Keysと進み、Create an IBM Cloud API Keyをクリックして適当な名前をつけてCreate
生成されたAPI Keyをメモ

２. SwaggerHubに戻りAdd New IntegrationからManager Integrations => Choose Integration to AddからIBM API Connectを追加

名前を適当につけて、先ほど取得したAPI Keyを入れる
AuthenticateをクリックするとIBM Cloud上の組織名が一覧に出てくるので選択してCreateまたはCreate and Executeを実行（Createだと連携の設定だけが作られ、ExecuteもするとAPI定義がAPI Connect上にデプロイされる）

３.[ここからは同じ] IBM Cloudにログインしてデプロイ済みのAPI ConnectサービスのドラフトAPIを確認すると、先ほどのAPI定義がデプロイされていることがわかります。

４.API ConnectのAPI定義作成のGUI画面です。

５.もちろんソースを直接編集も可能です。

６.API Connectで拡張できる定義としてはアセンブルというのがあります。バックエンドの内部APIを呼び出したり、複数のAPIの呼び出し結果をマッシュアップしたり、JSON↔︎XML変換したり、Gateway ScriptというECMAScript5.1ベースのスクリプトを仕込んだりすることができます。

７.それではこのAPIを公開します。API Connectを使って公開することでIBM DataPower Gatewayを介してAPIコールができます。API Connectでは1~複数のAPIをグルーピングした「製品」と呼ばれる単位で公開します。製品タブから新規製品をクリックします。

８.適当な名前を入れて作成します。

９.先ほど作成したAPIを追加します。＋ボタンを押すとAPIが選択できます。

１０.続いてプランを作成します。ここでいわゆるAPIの無料プランとか有料プランなどを設定できます。例えば時間単位でアクセスできるコール数やバースト制限をかけることができます。ただし有料プランを作るには、API Connectサービス自体が無償のライト・プランではなくて有償プランでデプロイしておく必要があるので、ここではできません。
ここでは以下のように無料プランで1分に100コールまでの制限を設け、制限に達すると指定した時間が経過するまで呼び出しができなくなるようにしています。TwitterなどのAPIレート制限を想像していただければとわかりやすいかと思います。

１１.他に必要な情報を入れたら右上の保存ボタンをクリックします。

１２.保存ボタンの左横の↑ボタンをクリックして公開します。デフォルトでは公開ターゲットとしてSandboxというカタログが設定されています。API Connectでは「カタログ」という単位のターゲットに対してAPIのグループである「製品」を公開します。カタログは自由に追加できます。どういった基準でカタログを作ってもよいのですが、例えば部門単位とか業務単位とかが考えられます。（部門Aカタログと部門Bカタログと分けて、それぞれの「製品」を管理、など）

１３.まずはステージングされます。

１４.API Connectのトップのダッシュボード画面に行くとSandboxカタログがあるのがわかります。

１５.Sandboxをクリックすると先ほどステージングした製品があるのがわかります。

１６.メニューから公開をクリックします。

１７.可視性の編集という画面が出てきます。これは開発者ポータルというAPI利用者が閲覧・テストするためのAPI仕様公開するポータルサイトに対して、どのレベルで公開するかという設定です。ここでは閲覧は誰でもでき、サブスクライブするには開発者ポータルに登録して認証済みユーザーのみ、という設定にしています。