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.
The OpenAPI preview feature is only available today in the 1.x runtime. Information on how to create a 1.x function app can be found here.
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:
- Azure Functions developer reference.
- Azure Functions triggers and bindings concepts.
- Code and test Azure Functions locally.
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 page in your function app's Platform features.
Function API definition feature is not supported for beta runtime currently.
To enable the generation of a hosted OpenAPI definition and a quickstart definition, set API definition source to Function (Preview). 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.
|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.
|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|
|operationID*||Route + Allowed verbs||Route + Allowed Verbs|
*The operation ID is required only for integrating with PowerApps and Flow.
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:
- Browse to API Definition (preview) in your function app settings.
- Set API definition source to Function.
- Click Generate API definition template and then Save to create a template definition for modifying later.
- Note your API definition URL and key.
- Set up continuous integration/continuous deployment (CI/CD).
- 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.
- Getting started tutorial. Try our walkthrough to see an OpenAPI definition in action.
- Azure Functions GitHub repository. Check out the Functions repository to give us feedback on the API definition support preview. Make a GitHub issue for anything you want to see updated.
- Azure Functions developer reference. Learn about coding functions and defining triggers and bindings.