Skip to content

cli.md

Latest commit

 

History

History
169 lines (117 loc) · 3.71 KB

cli.md

File metadata and controls

169 lines (117 loc) · 3.71 KB

CLI Guide

azure-functions-openapi ships with a CLI entry point for generating OpenAPI output from decorated handlers.

Install

pip install azure-functions-openapi

Then verify:

azure-functions-openapi --help

Command overview

Current command set:

  • generate: build OpenAPI spec in JSON or YAML

generate command

Basic usage

azure-functions-openapi generate

By default this prints JSON to stdout using:

  • title: API
  • version: 1.0.0
  • OpenAPI version: 3.0.0

Common examples

Generate JSON to stdout:

azure-functions-openapi generate --title "Todo API" --version "1.2.0"

Generate YAML to stdout:

azure-functions-openapi generate --format yaml --title "Todo API"

Write JSON to file:

azure-functions-openapi generate --output openapi.json --format json

Write YAML to file:

azure-functions-openapi generate --output openapi.yaml --format yaml

Generate OpenAPI 3.1 output:

azure-functions-openapi generate --openapi-version 3.1 --output openapi-3.1.json

Import your function app so routes are registered:

azure-functions-openapi generate --app function_app --title "Todo API"

Pretty-print JSON output:

azure-functions-openapi generate --app function_app --pretty --output openapi.json

Options reference

Option Alias Values Default Description
--app - module or module:var - Import module before generating so @openapi decorators register routes
--title - any string API OpenAPI info.title
--version - any string 1.0.0 OpenAPI info.version
--output -o file path stdout Write generated content to file
--format -f json, yaml json Output serialization format
--openapi-version - 3.0, 3.1 3.0 OpenAPI schema version
--pretty -p flag false Pretty-print JSON output (adds indentation); no effect on YAML

Exit codes

Code Meaning
0 Success
1 Runtime or generation error
2 Invalid CLI arguments (argparse parse error)

Validate generated output

Use a validator in local checks and CI:

pip install openapi-spec-validator
openapi-spec-validator openapi.json

For YAML:

openapi-spec-validator openapi.yaml

CI example

name: OpenAPI Validation

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install tools
        run: pip install azure-functions-openapi openapi-spec-validator
      - name: Generate spec
        run: azure-functions-openapi generate --openapi-version 3.1 --output openapi.json
      - name: Validate spec
        run: openapi-spec-validator openapi.json

Troubleshooting

command not found

  • Confirm package installed in active environment
  • Use python -m azure_functions_openapi.cli --help as fallback

Empty paths in output

  • Ensure app handlers are decorated with @openapi

  • Pass --app <module> so decorated routes are registered before generation:

    azure-functions-openapi generate --app function_app --title "My API"

  • Use module:variable syntax when the FunctionApp instance is not named app:

    azure-functions-openapi generate --app function_app:my_app --title "My API"

Unsupported version error

  • Use only --openapi-version 3.0 or --openapi-version 3.1

Related docs