DEV Community

Albert Bennett
Albert Bennett

Posted on

How to: Enable Open API with HTTP trigger Azure Function Apps

This was was a feature that I had been on the look out for a few years now. Back about 3 years ago it was a bit of a blocker for us on a project because, at the time it wasn't possible to generate an Open API (Swagger doc) from an Azure Function App to suit our needs.
Nowadays, it's very easy to do. I've placed the demo code here on GitHub
Well... that is assuming that you aren't starting from a new function app because in Visual Studio 2019, there is a template project that implements this. See image below:
image
Now back to the tutorial.

Step 1:
You need to install a NuGet package in your function app. The one you need is called: Microsoft.Azure.WebJobs.Extensions.OpenApi right now it is in preview v0.8.1.
When you run the project, you will see a set of dynamic endpoints. These are the various Open API endpoints for your function app that you can use to access the Open API.
image
image

Step 2:
Attributes... these are used to tell the NuGet package how/ what to display in your Open API. For generating your Open API in c# there are a lot of them to check out, from defining query parameters and request bodies, to responses and security. Below I have shown an example of how the OpenApiOperation and the OpenApiResponseWithBody attributes can be used with an Azure Function.

        [FunctionName("Function1")]
        [OpenApiOperation(operationId: "Function1", tags: new[] { "name" })]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "Returns a 200 response with text")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "get", Route = null)] HttpRequest req,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
Enter fullscreen mode Exit fullscreen mode

As you can see below the effects of adding these attributes to the Azure Function has on the Open API.
image
It's worth noting here that to add an operation to your Open API you need to add the OpenApiOperation attribute to the appropriate HTTP trigger in your Function App. Although you can also use the OpenApiIgnore attribute to ignore the rendering of Http Triggers in your API as well if needs be.

Notes:

  1. When you deploy the function app to Azure you can view the swagger doc from the function app as well by going to the endpoint /api/swagger/ui

If you found something useful in here, feel free to like the Post.

Discussion (0)