Publishing OpenAPI Document from Azure Functions to Azure API Management within CI/CD Pipeline :backhand_index_pointing_left:
Throughout this post, I'm going to discuss how to publish the OpenAPI document to APIM, after locally running the Azure Functions app as a background process and generating the OpenAPI document within the GitHub Actions workflow.
The OpenAPI document generated from the pipeline above has https://localhost:7071/api as the default server URL. However, the actual server URL must be the format of https://<azure-functions-app>.azurewebsites.net/api after deployment. Therefore, although you haven't deployed the function app yet, the generated OpenAPI document must have the deployed app URL. According to the doc, the extension offers the feature to apply the server URL.
Set the environment variable, OpenApi__HostNames, so the actual server URL is added on top of localhost (line #4).
Set the environment variable, AZURE_FUNCTIONS_ENVIRONMENT, to Production so that localhost is omitted and only the server URL is rendered as if the function app is running on Azure (line #5).
Generally speaking, local.settings.json is excluded from the repository because it's supposed to use for local development. But, it's required to run the function app locally as a background process. Therefore, it's always a good idea to create one. The revised action below copies the local.settings.sample.json to local.settings.json (line #12).
With these three points in mind, let's update the GitHub Action (line #4,5,12).
As mentioned above, this action just copies the existing local.settings.sample.json file to local.settings.json, but it's not common. Therefore, in most cases, you should create the local.settings.json file by yourself, and it MUST include the environment variable, FUNCTIONS_WORKER_RUNTIME (line #3). In other words, the minimal structure of local.settings.json looks like below (assuming you use the in-proc worker):
Now, we've got the OpenAPI document from the CI/CD pipeline, with the actual server URL, without deploying the function app.
Publish to Azure API Management
This time, let's publish the OpenAPI document to APIM. Although there are many ways to do it, let's use Azure Bicep and deploy it through Azure CLI in this post. Here's the first part of the bicep file. Use the existing keyword to get the existing APIM resource details.
It looks simple, except those two attributes – format and value (line #12-13). Therefore, it's better to understand what those two attributes are. For more comprehensive details, you can visit the Azure Bicep Template Reference.
TO use the JSON string parsed from the OpenAPI document:
OpenAPI v2: Set the format value to swagger-json.
OpenAPI v3: Set the format value to openapi+json.
Assign the JSON string to the value attribute.
TO use the publicly accessible URL for the OpenAPI document:
OpenAPI v2: Set the format value to swagger-link-json.
OpenAPI v3: Set the format value to openapi+json-link.
Assign the publicly accessible URL to the value attribute.
Even if the first approach is doable, I wouldn't recommend it because it's too painful to parse the OpenAPI document to the JSON string that the bicep file can understand. Therefore, I would suggest using the second approach by storing the OpenAPI document to Azure Blob Storage right after it's generated from the pipeline.
Once you complete authoring the bicep file, run the Azure CLI command to deploy the API to APIM.