OpenAPI 2.0 metadata support in Azure Functions (preview)

OpenAPI 2.0 (formerly Swagger) metadata support in Azure Functions is a preview feature that you can use to write an OpenAPI 2.0 definition inside a function app. You can then host that file by using the function app.

OpenAPI metadata allows a function that's hosting a REST API to be consumed by a wide variety of other software. This software includes Microsoft offerings like PowerApps and the API Apps feature of Azure App Service, third-party developer tools like Postman, and many more packages.

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

Tip

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

Enable OpenAPI definition support

You can configure all OpenAPI settings on the API Definition (preview) page in your function app settings.

To enable the generation of a hosted OpenAPI definition and a quickstart definition, set API definition source to Function. External URL allows your function to use an OpenAPI definition that's hosted elsewhere.

Generate a Swagger skeleton from your function's metadata

A template can help you start writing your first OpenAPI definition. The definition template feature creates a sparse OpenAPI definition by using all the metadata in the function.json file for each of your HTTP trigger functions. You'll need to fill in more information about your API from the OpenAPI specification, such as request and response templates.

For step-by-step instructions, see the getting started tutorial.

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 the generated definition

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

Swagger.json Portal UI Function.json
Host Function app settings > 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

*The operation ID is required only for integrating with PowerApps and Flow.

Note

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

To learn more, see Customize your Swagger definition for PowerApps.

Use CI/CD to set an API definition

You must enable API definition hosting in the portal before you enable source control to modify your API definition from source control. Follow these instructions:

  1. Browse to API Definition (preview) in your function app settings.
    1. Set API definition source to Function.
    2. Click Generate API definition template and then Save to create a template definition for modifying later.
    3. Note your API definition URL and key.
  2. Set up continuous integration/continuous deployment (CI/CD).
  3. Modify 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 that you noted in step 1.c.

Next steps