Creating OpenAPI 2.0 (Swagger) Metadata for a Function App (Preview)

This document guides you through the step by step process of creating an OpenAPI Definition for a simple API hosted on Azure Functions.

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

What is OpenAPI (Swagger)?

Swagger Metadata is a file that defines the functionality and operating modes of your API, and allows a function hosting a REST API to be consumed by a wide variety of other software. Microsoft offerings like PowerApps and API Apps, as well as 3rd party developer tooling like Postman and many more packages all allow your API to be consumed with a Swagger definition.

Creating a Function with a simple API

To create an OpenAPI definition, we first need to create a Function with a simple API. If you already have an API hosted on a Function App, you can skip straight to the next section

  1. Create a new Function App.
    1. Azure portal > + New > Search for "Function App"
  2. Create a new HTTP trigger function inside your new Function App
    1. Your function is pre-populated with code defining a very simple REST API.
    2. Any string passed to the Function as a query parameter or in the body is returned as "Hello {input}"
  3. Go to the Integrate tab of your new HTTP Trigger function
    1. Toggle Allowed HTTP methods to Selected methods
    2. In Selected HTTP methods uncheck every verb except POST. Selected HTTP Methods
    3. This step will simplify your API definition later on.

Enabling API Definition Support

  1. Navigate to your function name > API Definition (preview)
  2. Set API Definition Source to Internal
    1. This step enables a suite of OpenAPI options for your Function App, including an endpoint to host an OpenAPI file from your Function App's domain, an inline copy of the OpenAPI Editor, and a quickstart definition generator. Enabled Definition

Creating your API Definition from a template

  1. Click Generate API Definition template
    1. This step scans your Function App for HTTP Trigger functions and uses the info in functions.json to generate an OpenAPI document.
  2. Add an operation object to paths: /api/yourfunctionroute post:

    1. The quickstart OpenAPI document is an outline of a full OpenAPI doc. It requires more metadata to be a full OpenAPI definition, such as operation objects and response templates.
    2. The sample operation object below has a filled out produces/consumes section, a parameter object, and a response object.
       post:
         operationId: /api/yourfunctionroute/post
         consumes: [application/json]
         produces: [application/json]
         parameters:
           - name: name
             in: body
             description: Your name
             x-ms-summary: Your name
             required: true
             schema:
               type: object
               properties:
                 name:
                   type: string
         description: >-
           Replace with Operation Object
           #http://swagger.io/specification/#operationObject
         responses:
           '200':
             description: A Greeting
             x-ms-summary: Your name
             schema:
               type: string
         security:
           - apikeyQuery: []
    
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.

  1. Click save to save your changes Adding Template Definition

Using Your API Definition

  1. Copy your API definition URL and paste it into a new browser tab to view your raw OpenAPI document.
  2. You can import your OpenAPI document to any number of tools for testing and integration using that URL.
    1. Many Azure resources are able to automatically import your OpenAPI doc using the API Definition URL that is saved in your Function application settings. As a part of the Function API definition source, we update that url for you.

Using the Swagger UI to test your API definition

There are testing tools built in to the UI view of the imbedded API definition editor. Add your API key, and then use the Try this operation button under each method. The tool will use your API Definition to format the requests and successful responses will indicate that your definition is correct.

Steps:

  1. Copy your function API key
    1. The API key can be found in your HTTP Trigger Function under function name > Keys > Function Keys Function key
  2. Navigate to the API Definition (preview) page.
    1. Click Authenticate and add your Function API key to the security object at the top. OpenAPI key
  3. select /api/yourfunctionroute > POST
  4. Click Try it out and enter a name to test
  5. You should see a SUCCESS result under Pretty API Definition test

Next steps