Today, we are announcing a preview NuGet package, template, and Visual Studio v16.10 publishing support for creating OpenAPI enabled Azure Functions.
The OpenAPI Specification is an API description format for REST APIs and has become the leading convention for describing HTTP APIs. An OpenAPI description effectively describes your API surface; endpoints, operation parameters for each, authentication methods, and other metadata. As a part of the ecosystem already rich with tools and open-source packages for .NET, we wanted to extend this capability to Azure Functions.
In the early days of Azure Functions, there was a preview feature that allow you to use the OpenAPI specification to document your functions or endpoints. This feature experience was built into the Azure Portal, but never realized in the GA version of the product.
Brady Gaster showed the benefit of a well-designed API using ASP.NET Core and OpenAPI in this post on the ASP.NET Blog.
Getting Started
Using Visual Studio 16.10 or later, create a new Azure Functions project and choose the HttpTrigger template – “Http Trigger with OpenAPI”.
The new function is bootstrapped with the necessary implementation for OpenAPI support. When running the application, notice not only does the function emit the “Function1” endpoint as expected but also additional routes for a dynamic endpoint for OpenAPI document, Swagger document in JSON or YAML, Authentication redirects and the Swagger UI interactive app.
The additional routes are encapsulated when the function app is deployed, meaning that they are there but not exposed as public viewable routes.
Browsing to the `/api/swagger/ui` endpoint show the Swagger UI page which can be thought of as interactive documentation
The dynamic endpoint for the OpenAPI document accepts the version (v2 or v3) of the specification and the extension preferred (json or yaml). In the following example /api/openapi/v2.json returns the appropriate version of the specification in JSON. Note that the emitted JSON includes the operationId, an attribute used to provide a unique string-based identifier for each operation in the API. See more about generating HTTP API clients using Visual Studio Connected Services.
Publish and CI/CD support
As you can imagine, yes right click publish support is here for you. Using the known publishing dialog, pushing your OpenAPI enable function to AppService or Containers and provisioning the needed Azure resources are all handled.
Nothing has changed with the publishing of a new Azure Function, unless you want to also want to use this as a custom connector for your Power Apps. In Visual Studio 16.9 we added support for publishing to an existing Azure API Management service instances and creating new Consumption-mode instances of Azure API Management so you can use the monitoring, security, and integration capabilities of API Management.
In Visual Studio 16.10, the functionality is extended to support the Azure Function project that includes OpenAPI capabilities. When you are publishing an Azure Function with OpenAPI, the API Management tab allowing for selecting an existing instance or creating a new one.
Once the publish operation completes, you’ll be able to view and test the API operations within the API Management portal blade.
As an additional option, the provisioning and deployment of the Azure Function and related resources is now also available as a GitHub Action if your code in committed to a repository.
On finishing the publish dialog, a GitHub Action is created and committed to the repository triggered by a push of any change.
Using either method publishes or updates your Azure Function, creates or updates the API Management instance AND imports the function for you.
Azure API Management
Typically when adding a new API to the API Management instance you would have to manually define names, operations, parameters, endpoints and other metadata. When using the OpenAPI Extension, this is all done for you and any subsequent updates are also handled automatically. The following image shows the “Run” operation from the Azure Function along with all the configuration complete.
Add OpenAPI support to existing projects
For adding OpenAPI support to your existing Azure Functions, the Microsoft.Azure.WebJobs.Extensions.OpenApi package is available for .NET functions using the HttpTrigger. With just a few method decorators, the package makes your existing functions endpoints optimized for discovery.
public static class SayHello
{
[FunctionName("SayHello")]
[OpenApiOperation(operationId: "Run", tags: new[] { "name" })]
[OpenApiParameter(name: "name", In = ParameterLocation.Query, Required = true, Type = typeof(string), Description = "Who do you want to say hello to?")]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "The OK response")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
string name = req.Query["name"];
…
return new OkObjectResult(responseMessage);
}
}
}
In this example, the AuthorizationLevel is set to “Anonymous”, however with the OpenApiSecurity decorator, using either "code" through querystring or "x-functions-key" through headers; additional security can be applied.
Summary
To learn more about the Azure Functions OpenAPI extension, visit the project on GitHub and checkout the preview documentation. As always. We’re interested in your feedback, please comment below and/or provide more in the issues tab on the repository.
We can’t wait to see what you build.
Microsoft
