Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
Help us understand the problem. What is going on with this article?

[更新] SwaggerHubで作成したAPI定義をIBM Cloud API Connectに公開

More than 1 year has passed since last update.

更新情報

  • 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定義

  1. SwaggerHubにログインして、新規API作成
    Kobito.YKOIQK.png

  2. ここではテンプレートにすでに定義済みのサンプルを選択します。なお注意点としてOpen API 2.0(デフォルト)を選択します。3.0にはAPI Connectは2017/12/20時点、まだ対応していないため連携ができなくなります。
    Kobito.TNXiR6.png

  3. こんな感じです。
    Kobito.PQ49SZ.png

API Connectへデプロイ

  1. プラグボタンをクリックして連携先を追加します。
    Kobito.7MWQU9.png

  2. API Connectを選択して追加します。
    Kobito.xdU1lE.png

  3. IBM Cloudのアカウント情報を入れます。ID/PWを入れてValidate Credentialsをクリックすると、組織を選択できるのでIBM Cloudに設定してある組織を選択してCreate & Executeします。
    Kobito.WslQif.png

Kobito.hW9wMZ.png

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

  • Manager => Access(IAM) => IBM Cloud API Keysと進み、Create an IBM Cloud API Keyをクリックして適当な名前をつけてCreate
    image.png

  • 生成されたAPI Keyをメモ
    image.png

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

image.png

  • 名前を適当につけて、先ほど取得したAPI Keyを入れる
    image.png

  • AuthenticateをクリックするとIBM Cloud上の組織名が一覧に出てくるので選択してCreateまたはCreate and Executeを実行(Createだと連携の設定だけが作られ、ExecuteもするとAPI定義がAPI Connect上にデプロイされる)
    image.png

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

4.API ConnectのAPI定義作成のGUI画面です。
Kobito.8z4cP9.png

5.もちろんソースを直接編集も可能です。
Kobito.mLtNQ8.png

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

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

8.適当な名前を入れて作成します。
Kobito.UoAW2u.png

9.先ほど作成したAPIを追加します。+ボタンを押すとAPIが選択できます。
Kobito.sE2udJ.png

Kobito.EG37HI.png

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

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

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

13.まずはステージングされます。
Kobito.cQWyVH.png

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

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

16.メニューから公開をクリックします。
Kobito.pwhZ7n.png

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

18.公開されました。
Kobito.ercn7G.png

19.API Connectで付与されるエンドポイントはダッシュボードのカタログの設定のゲートウェイから確認できます。ホスト名(IBM Cloud API Connect共通)/ユーザー組織名/カタログ名というパスになります。sbはSandboxカタログのことですね。
Kobito.rb4p3x.png

20.上記パスの後ろにAPI定義で設定した基本パスとパスを追加し、必要に応じてパラメータを入れてGETなりPOSTなりします。ここでは呼び出すバックエンドも何もないのでGETしても特に何もありません。

21.分析画面に行くと、公開したAPIがどれくらいコールされたかとか応答時間とかエラー状況などをグラフィカルに見ることができます。
Kobito.u61LU3.png

22.API Connectの開発者ポータルにAPIを公開するとこんな感じになります。先ほど公開した「製品」が表示され、含まれるAPIやプランの詳細が確認できます。サブスクライブ(配信登録)するにはログインが必要です。
Kobito.h3qPfM.png
Kobito.HWdncn.png

23.開発者ポータルのURLはカタログの設定からポータルのメニューで確認できます。デフォルトでは開発者ポータルは作成されないので、ポータルを選択して有効化しておく必要があるのでご注意ください(ここでは有効化済みです)。
Kobito.atQ2yQ.png

まとめ

以上でSwaggerHubで作成したOpen API定義をAPI Connectにデプロイして公開しました。

参考

rinaxsumomo
このサイトの掲載内容は私自身の見解であり、必ずしも私の所属組織・企業の立場、戦略、意見を代表するものではありません。公開情報および著者による検証環境をベースに執筆しておりますが、誤解・誤植を含んでいる可能性があります。ご利用の際は自己責任で必ず最新の情報を自ら確認されますようお願いします。特に予期せぬ課金請求などが発生しても著者は一切責任を持ちません。また誤りを見つけられた方は是非ご一報ください。
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away