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
- Windows only:
-
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
- Linux:
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 |
- Linux/Mac CLI:
| # Bash | |
| ./azfuncopenapi \ | |
| --project <PROJECT_PATH> \ | |
| --configuration Debug \ | |
| --target netcoreapp2.1 \ | |
| --version v2 \ | |
| --format json \ | |
| --output output \ | |
| --console false |
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.