Azure Functions にはもともとAPI定義(API Definition)という機能があって、外部のどこかにOpenAPI 2.0(Swagger 2.0)の定義ファイルを置いてそのURLを登録できる機能がありました。(特に連携などなし)
今回追加されたPreview機能ではその機能に追加して定義されているHttpTriggerなFunctionから自動的にSwagger2.0な定義ファイルを生成・テストできる機能が増えました。
詳細は公式ドキュメントに概要・手順が載っていますのでそちらをどうぞ。
- Creating OpenAPI 2.0 (Swagger) Metadata for a Function App (Preview)
- OpenAPI 2.0 (Swagger) Metadata support in Azure Functions (Preview)
さて実際に試してみましょう。API定義に含められるのは外部からアクセスできるHttpTriggerが対象となります。なのでまずはHttpTriggerなFunctionを作りましょう。(言語はなんでもよいです)
作成後、統合(Integrete)で利用可能なHTTPメソッドをPOSTだけにとりあえずしたりします。
できたら左下にある「API Definition(Preview)」を選びます。
ExternalのSet External Definition URLはこれまで通りの機能です。ここで「Internal」を選択すると新しい機能が利用できます。
最初は空なのでエラーになってますね。ここですでに定義されているFunctionから生成するために「Load Generated API Definition」をクリックします。すると自動的にある程度のAPI定義が生成されます。
最低限は埋まってますね。ちゃんと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ボタンをクリックします。
無事動作しました。(よく見るとテスト用UIがどこで動いてるかわかって面白いですね(CORSの既定値のホストでもありますね)
出来上がったAPI定義はAPI Definition URL欄にあるURLで参照できるのでこちらを伝えればいいでしょう。
ちなみにAPIのURLは既定でFunction名になりますが、IntegrateのRoute Template欄を編集すれば希望するURLになります。
この場合、 /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定義があるだけでクライアント側の開発効率はぐっと上がると思いますので、ぜひ活用しましょう!
質問などはforumsや StackOverFlowへ、問題点などあれば GitHubへどうぞ。要望などはUservoiceもあります。(と公式Blogのほうに書いてました)
ピンバック: Azure Update (2017.04.06) | ブチザッキ