Skip to content

Latest commit

 

History

History
273 lines (181 loc) · 13 KB

enable-open-api-endpoints-out-of-proc.md

File metadata and controls

273 lines (181 loc) · 13 KB
Raw

Enable OpenAPI Endpoints on Azure Functions – Out-of-Process Model

OpenAPI metadata supports in Azure Functions is now available with this extension, Azure Functions OpenAPI Extension (Out-of-Process Worker). With this extension, you can directly let your API endpoints be discoverable.

Important

This extension supports both .NET Framework 4.8.x and .NET 7+. If you want to use .NET 6, find this in-process model.

OpenAPI metadata allows wide variety of other software and applications to consume an Azure Functions app hosting HTTP APIs. The software and applications include Microsoft products and services like Power Platform, API Management and third-party tools like Postman.

Prerequisites

To get yourself started, you need to have the followings installed on your local machine.

Important

This extension is currently available in both .NET Framework 4.8.x and .NET 7+ runtime.

Create Function App

Firs of all, create a function app on your local machine.

func init MyOpenApiFunctionApp --worker-runtime dotnetIsolated

Navigate to the project directory

cd MyOpenApiFunctionApp

Add a function to your project by using the following command, where the --name argument is the unique name of your function (MyHttpTrigger) and the --template argument specifies HTTP trigger.

func new --name MyHttpTrigger --template "HTTP trigger"

Your Azure Functions app structure might look like this:

Azure Functions app structure in Visual Studio Code

Run the Function app on your local by running the command below:

func host start

Open a web browser and type the following URL, and you will be able to see the Functions app is up and running, which returns the response.

http://localhost:7071/api/MyHttpTrigger

Azure Functions run result on a web browser

Enable OpenAPI Document

To enable OpenAPI document, you will need to install a NuGet package, Microsoft.Azure.Functions.Worker.Extensions.OpenApi.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.OpenApi

With Visual Studio Code, open your HTTP trigger, MyHttpTrigger.cs, to enable the OpenAPI metadata, and add attribute classes on top of the Function(...) decorator.

namespace MyOpenApiFunctionApp
{
    public static class MyHttpTrigger
    {
        // Add these three attribute classes below
        [OpenApiOperation(operationId: "greeting", tags: new[] { "greeting" }, Summary = "Greetings", Description = "This shows a welcome message.", Visibility = OpenApiVisibilityType.Important)]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Summary = "The response", Description = "This returns the response")]
        // Add these three attribute classes above

        [Function("MyHttpTrigger")]
        public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req,
            FunctionContext executionContext)
...

Open Program.cs, to register the OpenAPI extension, and update the HostBuilder like the following:

namespace MyOpenApiFunctionApp
{
    public class Program
    {
        public static void Main()
        {
            var host = new HostBuilder()
            // Remove this line below
                .ConfigureFunctionsWorkerDefaults()
            // Remove this line above

            // Add these lines below
                .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())
            // Add these lines above
                .Build();

            host.Run();
        }
    }
}

Run the Function app again on your local by running the command below:

func host start

Open your web browser and type the following URL, and you will be able to see the Swagger UI page that describes your HTTP API endpoint above.

http://localhost:7071/api/swagger/ui

Swagger UI for Azure Functions app on local machine

Copy the link in the search bar at the top of the page and open it on another web browser window, and you will be able to see the OpenAPI 2.0 document generated on-the-fly.

swagger.json on local machine

Sign-in to Azure

Before you can publish your app, you must sign in to Azure.

  1. If you aren't already signed in, choose the Azure icon in the Activity bar, then in the Azure: Functions area, choose Sign in to Azure.... If you don't already have one, you can Create a free Azure account. Students can create a free Azure account for Students.

    Sign in to Azure within VS Code

    If you're already signed in, go to the next section.

  2. When prompted in the browser, choose your Azure account and sign in using your Azure account credentials.

  3. After you've successfully signed in, you can close the new browser window. The subscriptions that belong to your Azure account are displayed in the Side bar.

Deploy Function App to Azure

Once logged into Azure, create a function app and related resources in your Azure subscription and then deploy your code.

Important

Deploying to an existing function app overwrites the content of that app in Azure.

  1. Choose the Azure icon in the Activity bar, then in the Azure: Functions area, choose the Deploy to function app... button.

    Publish your project to Azure

  2. Provide the following information at the prompts:

    • Select folder: Choose a folder from your workspace or browse to one that contains your function app. You won't see this if you already have a valid function app opened.
    • Select subscription: Choose the subscription to use. You won't see this if you only have one subscription.
    • Select Function App in Azure: Choose - Create new Function App. (Don't choose the Advanced option, which isn't covered in this article.)
    • Enter a globally unique name for the function app: Type a name that is valid in a URL path. The name you type is validated to make sure that it's unique in Azure Functions.
    • Select a location for new resources: For better performance, choose a region near you.

  3. When completed, the following Azure resources are created in your subscription, using names based on your function app name:

    • A resource group, which is a logical container for related resources.
    • A standard Azure Storage account, which maintains state and other information about your projects.
    • A consumption plan, which defines the underlying host for your serverless function app.
    • A function app, which provides the environment for executing your function code. A function app lets you group functions as a logical unit for easier management, deployment, and sharing of resources within the same hosting plan.
    • An Application Insights instance connected to the function app, which tracks usage of your serverless function.

    A notification is displayed after your function app is created and the deployment package is applied.

  4. Select View output in this notification to view the creation and deployment results, including the Azure resources that you created. If you miss the notification, select the bell icon in the lower right corner to see it again.

    Create complete notification

Run Function App in Azure

  1. Back in the Azure: Functions area in the side bar, expand the new function app under your subscription. Expand Functions, and you will be able to see several functions including RenderSwaggerUI. Right-click (Windows) or Ctrl - click (macOS) on RenderSwaggerUI, and then choose Copy Function URL.

    Copy the function URL for the new HTTP trigger

  2. Paste this URL for the HTTP request into your browser's address bar, and execute the request. The URL that calls your HTTP-triggered function should be in the following format:

    http://<functionappname>.azurewebsites.net/api/swagger/ui

    You should be able to see the same Swagger UI page as what you saw in your local machine.

    Swagger UI for Azure Functions app on Azure

Clean-up Resources

When you continue to the next step, Integrating OpenAPI-enabled Azure Functions with Azure API Management, you'll need to keep all your resources in place to build on what you've already done.

Otherwise, you can use the following steps to delete the function app and its related resources to avoid incurring any further costs.

  1. In Visual Studio Code, press F1 to open the command palette. In the command palette, search for and select Azure Functions: Open in portal.

  2. Choose your function app, and press Enter. The function app page opens in the Azure portal.

  3. In the Overview tab, select the named link next to Resource group.

    Select the resource group to delete from the function app page

  4. In the Resource group page, review the list of included resources, and verify that they are the ones you want to delete.

  5. Select Delete resource group, and follow the instructions.

    Deletion may take a couple of minutes. When it's done, a notification appears for a few seconds. You can also select the bell icon at the top of the page to view the notification.

To learn more about Functions costs, see Estimating Consumption plan costs.

Next Steps

You have got an Azure Functions app with OpenAPI metadata enabled. In the next articles, you will be able to integrate this OpenAPI-enabled Azure Functions app with either Azure API Management, Azure Logic Apps or Power Platform.