Azure Functions の OpenAPI 2.0(Swagger)サポート [Preview]

Azure Functions にはもともとAPI定義(API Definition)という機能があって、外部のどこかにOpenAPI 2.0(Swagger 2.0)の定義ファイルを置いてそのURLを登録できる機能がありました。(特に連携などなし)
今回追加されたPreview機能ではその機能に追加して定義されているHttpTriggerなFunctionから自動的にSwagger2.0な定義ファイルを生成・テストできる機能が増えました。

詳細は公式ドキュメントに概要・手順が載っていますのでそちらをどうぞ。

さて実際に試してみましょう。API定義に含められるのは外部からアクセスできるHttpTriggerが対象となります。なのでまずはHttpTriggerなFunctionを作りましょう。(言語はなんでもよいです)
作成後、統合(Integrete)で利用可能なHTTPメソッドをPOSTだけにとりあえずしたりします。

image

できたら左下にある「API Definition(Preview)」を選びます。
image

API定義の画面が開きます。
image

ExternalのSet External Definition URLはこれまで通りの機能です。ここで「Internal」を選択すると新しい機能が利用できます。

image

最初は空なのでエラーになってますね。ここですでに定義されているFunctionから生成するために「Load Generated API Definition」をクリックします。すると自動的にある程度のAPI定義が生成されます。

image

最低限は埋まってますね。ちゃんとHttpTriggerのFunction分だけAPIも定義されてます。
ブレード(画面)の右側にはテスト用のUIも用意されていますのでこちらでテストできます。
とりあえず定義ファイル内で足らないところを埋めていきましょう。

producesとconsumes、parametersあたりを適切にします。descriptionは適宜修正してください(とりあえず既定のまま放置)
とりあえずJSONでPostされたものをJSONで返す感じのFunctionになっていると思うので、produces と consumes に application/json を指定します。(書き方はYAML形式です)
またparametersもテンプレートのままだとnameというのを受け取ることにしているので、そのようにします。
operationIdは必須ではありませんが、PowerAppsやMicrosoft Flowで必要となるみたいなのでそのままにしておきましょう。

参考までにこんな感じになります(抜粋)

paths:
  /api/HttpTriggerCSharp1:
    post:
      operationId: /api/HttpTriggerCSharp1/post
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: name
          in: body
          description: Your name
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      description: >-
        Replace with Operation Object
        #http://swagger.io/specification/#operationObject
      responses:
        '200':
          description: Success operation
      security:
        - apikeyQuery: []

編集できたらSaveボタンで保存しましょう。右側のテスト用UIも更新されたかと思います。
実際にテストする際は要認証(APIKey)の場合、最初にAuthenticationボタンでAPIKeyを入力してセットしておきます。
あとはTry this operationボタンをクリックしてパラメーターなどを入力してSend Requestボタンをクリックします。

image
image
image

無事動作しました。(よく見るとテスト用UIがどこで動いてるかわかって面白いですね(CORSの既定値のホストでもありますね)

出来上がったAPI定義はAPI Definition URL欄にあるURLで参照できるのでこちらを伝えればいいでしょう。

ちなみにAPIのURLは既定でFunction名になりますが、IntegrateのRoute Template欄を編集すれば希望するURLになります。
image
この場合、 /api/api2 とかでアクセスできます。(空欄だとFunction名なので例えば /api/HttpTriggerCSharp1 とかになります)
API定義にてLoad Generated API Definitionした場合もこの値を見てくれるので安心です。

※ もしAPI定義を編集してSaveしてもテストUIのパラメーターなどが反映されない場合はTry this operationで開いた部分をcloseボタンで閉じてから再度開きなおすか、API Definitionのページを再度開きなおせば反映されます。

Functionで定義したもろもろのメタデータ(先ほどのRoute Templateなど)がどのようにAPI定義に反映されるかはこちらのドキュメントに詳細が載っていますのでそちらを参照ください。

まとめ

HttpTriggerを使って何か処理させたりするケースだとAPI定義があるだけでクライアント側の開発効率はぐっと上がると思いますので、ぜひ活用しましょう!

質問などはforumsStackOverFlowへ、問題点などあれば GitHubへどうぞ。要望などはUservoiceもあります。(と公式Blogのほうに書いてました)

Azure Functions の OpenAPI 2.0(Swagger)サポート [Preview]」への1件のフィードバック

  1. ピンバック: Azure Update (2017.04.06) | ブチザッキ

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト /  変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト /  変更 )

%s と連携中