2 min read

Generating Open API Document through Command-Line for Azure Functions

Justin Yoo

Almost 1.5 years ago, I introduced the Swagger UI extension for Azure Functions and got a lot of feedback. One of them is to implement a CLI that generates the Open API document for the Azure Functions app. As I recently released this CLI, it's a good time to introduce the tool through this post.

Download CLI

GitHub repository has the CLI to download. As it's always tagged with cli-<version>, you can download the latest version of the CLI. In addition to this, the Open API extension supports Azure Functions from v1 to the latest one. Therefore, depending on your needs, download the appropriate CLI, based on your Azure Functions app runtime and operating system.

  • For Azure Functions v1

    • Windows only: azfuncopenapi-v<version>-net461-win-x64.zip
  • For Azure Functions v2 or later

    • Linux: azfuncopenapi-v<version>-netcoreapp3.1-linux-x64.zip
    • MacOS: azfuncopenapi-v<version>-netcoreapp3.1-osx-x64.zip
    • Windows: azfuncopenapi-v<version>-netcoreapp3.1-win-x64.zip

Generate Open API Document

Once you download the CLI above and implement the Open API extension on your Azure Functions app, you're good to go. Run the command below:

  • Windows CLI:
# PowerShell Console
azfuncopenapi `
--project <PROJECT_PATH> `
--configuration Debug `
--target netcoreapp2.1 `
--version v2 `
--format json `
--output output `
--console false
view raw 01-azfuncopenapi.ps1 hosted with ❤ by GitHub
  • Linux/Mac CLI:
# Bash
./azfuncopenapi \
--project <PROJECT_PATH> \
--configuration Debug \
--target netcoreapp2.1 \
--version v2 \
--format json \
--output output \
--console false
view raw 02-azfuncopenapi.sh hosted with ❤ by GitHub

Here are the options:

Option Description Default Value
--project|-p Project path. It can be a fully qualified project path including .csproj or project directory. Current directory
--configuration|-c Configuration value. It can be either Debug, Release or something else. Debug
--target|-t Target framework. It should be net4x (eg. net461) for Azure Functions v1, netcoreapp2.x (eg. netcoreapp2.1) for Azure Functions v2, and netcoreapp3.x (eg. netcoreapp3.1) for Azure Functions v3. netcoreapp2.1
--version|-v Open API spec version. It should be either v2 or v3. v2
--format|-f Open API document format. It should be either json or yaml. json
--output|-o Output directory for the generated Open API document. It can be a fully qualified directory path or relative path from <PROJECT_ROOT>/bin/<CONFIGURATION>/<TARGET_FRAMEWORK>. output
--console Value indicating whether to display the generated document to console or not. false

Run the CLI, and you'll be able to find either swagger.json or swagger.yaml generated in your designated output directory.

So far, I've introduced the CLI to generate Open API document for Azure Functions app. This tool is particularly useful when you work with API Management or custom connectors for Power Platform that require the Open API document.