Merge pull request #283552 from ggailey777/open-api-updates

[Functions] VS OpenAPI tutorial add isolated worker

Author: v-dirichards

.openpublishing.publish.config.json

@@ -380,6 +380,12 @@
       "branch": "main",
       "branch_mapping": {}
     },
+    {
+      "path_to_root": "functions-openapi-turbine-repair-isolated",
+      "url": "https://github.com/Azure-Samples/functions-openapi-turbine-repair-isolated",
+      "branch": "main",
+      "branch_mapping": {}
+    },
     {
       "path_to_root": "azure-functions-templates-v3",
       "url": "https://github.com/Azure/azure-functions-templates",

articles/azure-functions/media/openapi-apim-integrate-vs/apim-add-policy.png

@@ -1,58 +1,106 @@
 ---
-title: Create serverless APIs in Visual Studio using Azure Functions and API Management
-description: Use Visual Studio to create an HTTP triggered function along with an OpenAPI definition, which enables Azure API Management integration so that other apps and services can call your serverless function-based API.
+title: Create serverless APIs using Azure Functions and API Management
+description: Use Visual Studio to create an HTTP triggered function that uses an OpenAPI definition (formerly swagger) to expose a serverless API using API Management.
 ms.topic: tutorial
-ms.date: 01/18/2023
+ms.date: 08/04/2024
 ---
 
 # Create serverless APIs in Visual Studio using Azure Functions and API Management integration
 
-REST APIs are often described using an OpenAPI definition. This file contains information about operations in an API and how the request and response data for the API should be structured.
+REST APIs are often described using an OpenAPI definition (formerly known as Swagger) file. This file contains information about operations in an API and how the request and response data for the API should be structured.
 
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
-> * Create a serverless function project in Visual Studio
+> * Create the code project in Visual Studio
+> * Install the OpenAPI extension
+> * Add an HTTP trigger endpoint, which includes OpenAPI definitions
 > * Test function APIs locally using built-in OpenAPI functionality
-> * Publish project to a function app in Azure with API Management integration 
-> * Get the access key for the function and set it in API Management
+> * Publish project to a function app in Azure 
+> * Enable API Management integration 
 > * Download the OpenAPI definition file
 
-The serverless function you create provides an API that lets you determine whether an emergency repair on a wind turbine is cost-effective. Because both the function app and API Management instance you create use consumption plans, your cost for completing this tutorial is minimal.
-
-> [!NOTE]
-> The OpenAPI and API Management integration featured in this article is currently only supported for [in-process](functions-dotnet-class-library.md) C# class library functions. [Isolated worker process](dotnet-isolated-process-guide.md) C# class library functions and all other language runtimes should instead [use Azure API Management integration from the portal](functions-openapi-definition.md). 
+The serverless function you create provides an API that lets you determine whether an emergency repair on a wind turbine is cost-effective. Since you create both the function app and API Management instance in a consumption tier, your cost for completing this tutorial is minimal.
 
 ## Prerequisites
 
 + [Visual Studio 2022](https://azure.microsoft.com/downloads/). Make sure you select the **Azure development** workload during installation. 
 
 + An active [Azure subscription](../guides/developer/azure-developer-guide.md#understanding-accounts-subscriptions-and-billing), create a [free account](https://azure.microsoft.com/free/dotnet/) before you begin.
 
-## Create a Functions project
+## Create the code project
 
-The Azure Functions project template in Visual Studio creates a project that you can publish to a function app in Azure. You'll also create an HTTP triggered function supports OpenAPI definition file (formerly Swagger file) generation.
+The Azure Functions project template in Visual Studio creates a project that you can publish to a function app in Azure. You'll also create an HTTP triggered function from a template that supports OpenAPI definition file (formerly Swagger file) generation.
 
 1. From the Visual Studio menu, select **File** > **New** > **Project**.
 
 1. In **Create a new project**, enter *functions* in the search box, choose the **Azure Functions** template, and then select **Next**.
 
 1. In **Configure your new project**, enter a **Project name** for your project like `TurbineRepair`, and then select **Create**. 
 
-1. For the **Create a new Azure Functions application** settings, use the values in the following table:
+1. For the **Create a new Azure Functions application** settings, select one of these options for **Functions worker**, where the option you choose depends on your chosen process model:
+
+    ### [Isolated worker model](#tab/isolated-process)
+    
+    **.NET 8.0 Isolated (Long Term Support)**: Your C# functions run in the isolated worker model, which is recommended. For more information, see the [isolated worker model guide](dotnet-isolated-process-guide.md). 
+    
+    ### [In-process](#tab/in-process)
+
+    [!INCLUDE [functions-in-process-model-retirement-note](../../includes/functions-in-process-model-retirement-note.md)]
+
+    **.NET 8.0 (Long Term Support)**: Your C# functions run in the [in-process model](functions-dotnet-class-library.md), which will be retired. To learn more, see the [in-process model guide](functions-dotnet-class-library.md). 
+   
+    ---
+
+1. For the rest of the options, use the values in the following table: 
 
     | Setting      | Value  | Description                      |
     | ------------ |  ------- |----------------------------------------- |
-    | **Functions worker** | **.NET 6** | This value creates a function project that runs in-process on version 4.x of the Azure Functions runtime, which is required for OpenAPI file generation.    |
-    | **Function template** | **HTTP trigger with OpenAPI** | This value creates a function triggered by an HTTP request, with the ability to generate an OpenAPI definition file.  |
+    | **Function template** | **Empty** | This creates a project without a trigger, which gives you more control over the name of the HTTP triggered function when you add it later.   |
     | **Use Azurite for runtime storage account (AzureWebJobsStorage)**  | **Selected** | You can use the emulator for local development of HTTP trigger functions. Because a function app in Azure requires a storage account, one is assigned or created when you publish your project to Azure. |
     | **Authorization level** | **Function** | When running in Azure, clients must provide a key when accessing the endpoint. For more information, see [Authorization level](functions-bindings-http-webhook-trigger.md#http-auth). |
+
+1. Select **Create** to create the function project. 
+
+Next, you update the project by installing the OpenAPI extension for Azure Functions, which enables the discoverability of API endpoints in your app. 
+
+## Install the OpenAPI extension
+
+To install the OpenAPI extension: 
+
+1. From the **Tools** menu, select **NuGet Package Manager** > **Package Manager Console**. 
+
+1. In the console, run the following [Install-Package](/nuget/tools/ps-ref-install-package) command to install the OpenAPI extension:
+
+    ### [Isolated worker model](#tab/isolated-process)
 
-    ![Azure Functions project settings](./media/openapi-apim-integrate-vs/functions-project-settings.png)
+    ```command
+    NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
+    ```
+    You might need to update the [specific version](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.OpenApi), based on your version of .NET.
+   
+    ### [In-process model](#tab/in-process) 
+
+    ```command
+    NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi -Version 1.5.1
+    ```
+    You might need to update the [specific version](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi), based on your version of .NET.
+   
+    ---
+
+Now, you can add your HTTP endpoint function.
+
+## Add an HTTP endpoint function
+
+In a C# class library, the bindings used by the function are defined by applying attributes in the code. To create a function with an HTTP trigger:
+
+1. In **Solution Explorer**, right-click your project node and select **Add** > **New Azure Function**. 
 
-1. Select **Create** to create the function project and HTTP trigger function, with support for OpenAPI. 
+1. Enter **Turbine.cs** for the class, and then select **Add**.
 
-Visual Studio creates a project and class named `Function1` that contains boilerplate code for the HTTP trigger function type. Next, you replace this function template code with your own customized code. 
+1. Choose the **Http trigger** template, set **Authorization level** to **Function**, and then select **Add**. A Turbine.cs code file is added to your project that defines a new function endpoint with an HTTP trigger.
+
+Now you can replace the HTTP trigger template code with code that implements the Turbine function endpoint, along with attributes that use OpenAPI to define endpoint.
 
 ## Update the function code
 
@@ -65,10 +113,18 @@ The function uses an HTTP trigger that takes two parameters:
 
 The function then calculates how much a repair costs, and how much revenue the turbine could make in a 24-hour period. Parameters are supplied either in the query string or in the payload of a POST request. 
 
-In the Turbine.cs project file, replace the contents of the generated class library code with the following code:
+In the Turbine.cs project file, replace the contents of the class generated from the HTTP trigger template with the following code, which depends on your process model:
+
+ ### [Isolated worker model](#tab/isolated-process)
+    
+:::code language="csharp" source="~/functions-openapi-turbine-repair-isolated/TurbineRepair/Turbine.cs":::
+
+### [In-process model](#tab/in-process) 
 
 :::code language="csharp" source="~/functions-openapi-turbine-repair/TurbineRepair/Turbine.cs":::
 
+---
+
 This function code returns a message of `Yes` or `No` to indicate whether an emergency repair is cost-effective. It also returns the revenue opportunity that the turbine represents and the cost to fix the turbine.
 
 ## Run and verify the API locally
@@ -127,39 +183,43 @@ Before you can publish your project, you must have a function app in your Azure
     | **API name** | TurbineRepair | Name for the API. |
     | **Subscription name** | Your subscription | The Azure subscription to use. Accept this subscription or select a new one from the drop-down list. |
     | **Resource group** | Name of your resource group | Select the same resource group as your function app from the drop-down list.   |
-    | **API Management service** | New instance | Select **New** to create a new API Management instance in the serverless tier.   |
+    | **API Management service** | New instance | Select **New** to create a new API Management instance in the same location in the serverless tier. Select **OK** to create the instance.  |
 
     :::image type="content" source="media/openapi-apim-integrate-vs/create-api-management-api.png" alt-text="Create API Management instance with API":::
 
 1. Select **Create** to create the API Management instance with the TurbineRepair API from the function integration.
 
-1. select **Finish**, verify the Publish page says **Ready to publish**, and then select **Publish** to deploy the package containing your project files to your new function app in Azure. 
+1. Select **Finish** and after the publish profile creation process completes, select **Close**.
+
+1. Verify the Publish page now says **Ready to publish**, and then select **Publish** to deploy the package containing your project files to your new function app in Azure. 
 
     After the deployment completes, the root URL of the function app in Azure is shown in the **Publish** tab. 
 
 ## Get the function access key
 
 1. In the **Publish** tab, select the ellipses (**...**) next to **Hosting** and select **Open in Azure portal**. The function app you created is opened in the Azure portal in your default browser. 
 
-1. Under **Functions**, select **Functions** > **TurbineRepair** then select **Function keys**. 
+1. Under **Functions** on the **Overview page**, select > **Turbine** then select **Function keys**. 
 
     :::image type="content" source="media/openapi-apim-integrate-vs/get-function-keys.png" alt-text="Get an access key for the TurbineRepair function":::
 
-1. Under **Function keys**, select **default** and copy the **value**. You can now set this key in API Management so that it can access the function endpoint.
+1. Under **Function keys**, select the *copy to clipboard* icon next to the **default** key. You can now set this key you copied in API Management so that it can access the function endpoint.
 
 ## Configure API Management
 
-1. In the **Publish** tab, select the ellipses (**...**) next to **Hosting** and select **Open API in Azure portal**. The API Management instance you created is opened in the Azure portal in your default browser. This API Management instance is already linked to your function app. 
+1. In the function app page, expand **API** and select **API Management**.
 
-1. Under **APIs**, select **OpenAPI Document on Azure Functions** > **POST Run**, then under **Inbound processing** select **Add policy**.
+1. If the function app isn't already connected to the new API Management instance, select it under **API Management**, select **API** > **OpenAPI Document on Azure Functions**, make sure **Import functions** is checked, and select **Link API**. Make sure that only **TurbineRepair** is selected for import and then **Select**. 
 
-    :::image type="content" source="media/openapi-apim-integrate-vs/apim-add-policy.png" alt-text="Add an inbound policy to the API":::
+1. Select **Go to API Management** at the top of the page, and in the API Management instance, expand **APIs**.
+ 
+1. Under **APIs** > **All APIs**, select **OpenAPI Document on Azure Functions** > **POST Run**, then under **Inbound processing** select **Add policy** > **Set query parameters**.
 
 1. Below **Inbound processing**, in **Set query parameters**, type `code` for **Name**, select **+Value**, paste in the copied function key, and select **Save**. API Management includes the function key when it passes calls through to the function endpoint.
 
     :::image type="content" source="media/openapi-apim-integrate-vs/inbound-processing-rule.png" alt-text="Provide Function credentials to the API inbound processing rule":::
 
-Now that the function key is set, you can call the API to verify that it works when hosted in Azure.
+Now that the function key is set, you can call the `turbine` API endpoint to verify that it works when hosted in Azure.
 
 ## Verify the API in Azure
 
@@ -180,7 +240,7 @@ Now that the function key is set, you can call the API to verify that it works w
 
 ## Download the OpenAPI definition
 
-If your API works as expected, you can download the OpenAPI definition.
+If your API works as expected, you can download the OpenAPI definition for the new hosted APIs from API Management.
 
 1. 1. Under **APIs**, select **OpenAPI Document on Azure Functions**, select the ellipses (**...**), and select **Export**.
 
@@ -200,7 +260,7 @@ Select **Delete resource group**, type the name of your group in the text box to
 
 ## Next steps
 
-You've used Visual Studio 2022 to create a function that is self-documenting because of the [OpenAPI Extension](https://github.com/Azure/azure-functions-openapi-extension) and integrated with API Management. You can now refine the definition in API Management in the portal. You can also [learn more about API Management](../api-management/api-management-key-concepts.md).
+You've used Visual Studio 2022 to create a function that's self-documenting because of the [OpenAPI Extension](https://github.com/Azure/azure-functions-openapi-extension) and integrated with API Management. You can now refine the definition in API Management in the portal. You can also [learn more about API Management](../api-management/api-management-key-concepts.md).
 
 > [!div class="nextstepaction"]
 > [Edit the OpenAPI definition in API Management](../api-management/edit-api.md)