OpenAPI 2.0 Metadata support in Azure Functions (Preview)

This preview feature allows you to write an OpenAPI 2.0 (formerly Swagger) definition inside a Function App, and host that file using the Function App.

This is reference information for Azure Functions developers. If you're new to Azure Functions, start with the following resources:

What is OpenAPI metadata?

OpenAPI Metadata allows a function hosting a REST API to be consumed by a wide variety of other software. From 1st party offerings like PowerApps and API Apps, to 3rd party developer tooling like Postman, and many more packages.

Tip

We recommend starting with the getting started tutorial and then returning to this document to learn more about specific features.

Enabling OpenAPI definition Support

  • All OpenAPI settings can be configured in the API Definition (preview) page in your Function App settings.
  • Set API defintion source to Function to enable a hosted OpenAPI definition and quickstart definition generation.
    • External URL allows your Function to use an OpenAPI definition that is hosted elsewhere.

Generate a Swagger Skeleton from your Function Metadata

A template is an awesome way to get started writing your first OpenAPI definition. The definition template feature creates a sparse OpenAPI definition using all the metadata in the function.json for each of your HTTP trigger functions. You will need to fill in more information about your API from the OpenAPI specification, such as request and response templates.

Check out this getting started tutorial for step by step instructions

Available templates

Name Description
Generated Definition An OpenAPI definition with the maximum amount of information that can be inferred from the Function's existing metadata

Included Metadata in Generated Definition

The following table represents the portal settings and corresponding data in function.json as it is mapped to the generated skeleton Swagger.

Swagger.json Portal UI Function.json
Host Function app settings > Go to App Service Settings > Overview > URL not present
Paths Integrate > Selected HTTP methods Bindings: Route
Path Item Integrate > Route template Bindings: Methods
Security Keys not present
operationID* Route + Allowed verbs Route + Allowed Verbs

*Operation ID is only required for integrating with PowerApps + Flow

Note

x-ms-summary provides a display name in Logic Apps, Flow, and PowerApps.

Check out customize your Swagger definition for PowerApps to learn more.

Using CI/CD to set an API Definition

You must enable API Definition hosting in the portal before enabling source control to modify your API Definition from source control. Follow the instructions below.

  1. Navigate to API Definition (preview) in your Function App settings.
    1. Set API definition source to Function
    2. Click Generate API definition template then Save to create a template definition for modifying later.
    3. Note your API definition URL and key
  2. Set up CI/CD
  3. Modify your swagger.json in source control at \site\wwwroot\.azurefunctions\swagger\swagger.json

Now changes to swagger.json in your repository are hosted by your Function App at the API definition URL and key noted in step 1.3

Next steps