Generating OpenAPI Document from Azure Functions within CI/CD Pipeline
Published Feb 25 2022 04:00 PM 5,553 Views
Microsoft

From time to time, you might be facing some situations while using the Azure Functions OpenAPI extension for your Azure Functions development. One of them is that you are asked to generate the OpenAPI document from the function app right after the build and integrate it with Power Platform or Azure API Management. What if you want to do this process within your CI/CD pipeline?

 

Throughout this post, I'm going to discuss how to generate the OpenAPI document within the GitHub Actions workflow right after the function app build.

 

NOTE: Let's use the sample app provided by the Azure Functions OpenAPI Extension repository.

 

First of all, you need to install the Azure Functions Core Tools within your GitHub Actions workflow. Installing the tool varies depending on the runner OS. The command you're going to run the function app is like this:

 

func start

 

If it's the terminal environment on your local machine, just open one terminal session and run the function app. After that, you can open another terminal session for additional command-line jobs. That's not a problem at all. However, it's a totally different story when it's about the CI/CD pipeline because you can't open multiple terminal sessions there. Therefore, you have to run the function app as a background process.

 

Bash Shell Background Process

 

Bash shell offers & to run your app as the background process, like func start & (line #2). Therefore, you can run the shell commands to get the OpenAPI document like:

 

# Run the function app in background
func start &

# Send request to the function app and save it to swagger.json
curl http://localhost:7071/api/swagger.json > swagger.json

# Read swagger.json
cat swagger.json

 

How simple is that?

 

PowerShell Background Process

 

If you prefer PowerShell, use the Start-Process cmdlet with the -NoNewWindow switch to run the function app as the background process (line #2). For example, here are the commands on non-Windows runner:

 

# Run the function app in background
Start-Process -NoNewWindow func @("start")

# Send request to the function app and save it to swagger.json
Invoke-RestMethod -Method Get -Uri http://localhost:7071/api/swagger.json | ConvertTo-Json -Depth 100 | Out-File -FilePath swagger.json -Force

# Read swagger.json
Get-Content -Path swagger.json

 

On the other hand, the Start-Process cmdlet doesn't understand the command, func on the Windows runner. Therefore, you need a pre-process the func command (line #2, 5).

 

# Change the function app runner from .ps1 to .cmd
$func = $(Get-Command func).Source.Replace(".ps1", ".cmd")

# Run the function app in background
Start-Process -NoNewWindow "$func" @("start")

# Send request to the function app and save it to swagger.json
Invoke-RestMethod -Method Get -Uri http://localhost:7071/api/swagger.json | ConvertTo-Json -Depth 100 | Out-File -FilePath swagger.json -Force

# Read swagger.json
Get-Content -Path swagger.json

 

Now, you can get the OpenAPI document in PowerShell.

 

GitHub Actions Workflow

 

Now, we can get the OpenAPI document from the function app running as a background process. It means that you can get the document within the CI/CD pipeline. Here's the example in the GitHub Actions workflow. It only shows the function app build and OpenAPI document generation (line #26-33) for brevity.

 

name: Build

on:
  push:

jobs:
  build_and_test:
    name: Build
    runs-on: 'ubuntu-latest'

    steps:
    - name: Build solution
      shell: pwsh
      run: |
        pushd MyFunctionApp

        dotnet build . -c Release -v minimal

        popd

    - name: Generate OpenAPI document
      shell: pwsh
      run: |
        cd MyFunctionApp

        Start-Process -NoNewWindow func @("start","--verbose","false")
        Start-Sleep -s 60

        Invoke-RestMethod -Method Get -Uri http://localhost:7071/api/swagger.json | ConvertTo-Json -Depth 100 | Out-File -FilePath outputs/swagger.json -Force

        Get-Content -Path outputs/swagger.json -Raw

        cd ..

 


So far, we've walked through how to generate the OpenAPI document from the function app running as a background process within the CI/CD pipeline. The generated document can be stored somewhere as an artifact and integrated with other services like Power Platform or Azure API Management.

 

This article was originally published on Dev Kimchi.

Co-Authors
Version history
Last update:
‎Feb 26 2022 11:28 AM
Updated by: