Function App のための OpenAPI 2.0 (Swagger) メタデータの作成 (プレビュー)

このドキュメントでは、Azure Functions でホストされる単純な API のための OpenAPI 定義を作成する段階的なプロセスについて説明します。

これは、Azure Functions の開発者向けリファレンス情報です。 Azure Functions を初めて使用する場合は、先に次のリソースを参照してください。

OpenAPI (Swagger) とは

Swagger メタデータは、API の機能と動作モードを定義し、REST API をホストしている機能がさまざまなその他のソフトウェアによって使用できるようにするファイルです。 PowerApps や API Apps などのマイクロソフト製品だけでなく、Postman他の多くのパッケージのようなサード パーティ開発者ツールでも、Swagger 定義によって API を使用できるようになります。

単純な API を使用した関数の作成

OpenAPI 定義を作成するには、まず単純な API を使用した関数を作成する必要があります。 既に Function App でホストされている API がある場合は、次のセクションに直接進むことができます

  1. 新しい Function App を作成します。
    1. [Azure Portal] > + New >「Function App」を検索します
  2. 新しい Function App 内で新しい HTTP トリガー関数を作成します
    1. 関数には、非常に単純な REST API を定義するコードがあらかじめ設定されています。
    2. クエリ パラメーターとしてあるいは本文内で、関数に渡す任意の文字列は、「Hello {input}」として返されます
  3. 新しい HTTP トリガー関数の Integrate タブに移動します
    1. Allowed HTTP methodsSelected methods に切り替えます
    2. Selected HTTP methods で、POST 以外のすべての動詞をオフにします。 選択されている HTTP メソッド
    3. この手順により、後の API 定義が簡略化されます。

API 定義のサポートの有効化

  1. your function name > API Definition (preview) に移動します
  2. API Definition SourceFunction に設定します
    1. この手順により、Function App のドメインから OpenAPI ファイルをホストするエンドポイント、OpenAPI エディターのインライン コピー、クイック スタート定義ジェネレーターなどの、Function App のための一連の OpenAPI オプションが有効になります。 有効な定義

テンプレートからの API 定義の作成

  1. [Generate API Definition template] をクリックします。
    1. この手順では、Function App をスキャンして HTTP トリガー関数を探し、functions.json 内の情報を使用して OpenAPI ドキュメントを生成します。
  2. 操作オブジェクトを paths: /api/yourfunctionroute post: に追加します

    1. クイック スタート OpenAPI ドキュメントは完全な OpenAPI ドキュメントの概要を示します。 完全な OpenAPI 定義となるためには、操作オブジェクトや応答用テンプレートなどのさらに多くのメタデータが必要です。
    2. 以下のサンプル操作オブジェクトは、produces/consumes セクション、パラメーター オブジェクト、および応答用オブジェクトが入力されています。
       post:
         operationId: /api/yourfunctionroute/post
         consumes: [application/json]
         produces: [application/json]
         parameters:
           - name: name
             in: body
             description: Your name
             x-ms-summary: Your name
             required: true
             schema:
               type: object
               properties:
                 name:
                   type: string
         description: >-
           Replace with Operation Object
           #http://swagger.io/specification/#operationObject
         responses:
           '200':
             description: A Greeting
             x-ms-summary: Your name
             schema:
               type: string
         security:
           - apikeyQuery: []
    
メモ

x-ms-summary は、Logic Apps、Flow、および PowerApps の表示名を示します。

詳細については、「Customize your Swagger definition for PowerApps」を参照してください。

  1. [save] をクリックして変更内容を保存しますテンプレート定義の追加

API 定義の使用

  1. API definition URL をコピーして新しいブラウザー タブに貼り付け、未加工の OpenAPI ドキュメントを表示します。
  2. 使用する OpenAPI ドキュメントを、その URL を使用したテストおよび統合のための任意の数のツールにインポートできます。
    1. 多くの Azure リソースは、Function App 設定に保存されている API 定義 URL を使用して、OpenAPI ドキュメントを自動的にインポートできます。 Function API 定義ソースの一部として、その URL が更新されています。

API 定義をテストするための Swagger UI の使用

組み込み型の API 定義エディターの UI のビューにはテスト ツールが組み込まれています。 API キーを追加し、各メソッドの下にある [Try this operation] ボタンを使用します。 ツールは API 定義を使用して要求の書式を設定し、応答が正常な場合は定義が正しいことを示します。

手順:

  1. 関数 API キーをコピーします
    1. API キーはfunction name > Keys > Function Keys [Function key](関数キー) の HTTP トリガー関数から見つけることができます
  2. [API Definition (preview)] ページに移動します。
    1. [Authenticate] をクリックして、上部にあるセキュリティ オブジェクトに関数 API キーを追加します。 OpenAPI キー
  3. /api/yourfunctionroute > POST を選択します
  4. [Try it out] をクリックしてテストする名前を入力します
  5. Pretty の下に成功の結果が表示されます。API 定義テスト

次のステップ