azure-functions-openapi 0.15.0

OpenAPI (Swagger) integration for Azure Functions Python v2 programming model

Azure Functions OpenAPI

Read this in: 한국어 | 日本語 | 简体中文

OpenAPI (Swagger) documentation and Swagger UI for the Azure Functions Python v2 programming model.

Why Use It

Documenting Azure Functions HTTP APIs typically requires maintaining a separate OpenAPI spec by hand. azure-functions-openapi generates the spec automatically from decorated handlers, keeping documentation and code in sync.

Scope

• Azure Functions Python v2 programming model
• Decorator-based func.FunctionApp() applications
• HTTP-triggered functions documented with @openapi
• Pydantic schema generation (requires Pydantic v2)

This package does not support the legacy function.json-based v1 programming model.

Features

• @openapi decorator for operation metadata
• /openapi.json, /openapi.yaml, and /docs endpoints
• Query, path, header, body, and response schema support
• Swagger UI helper with security defaults
• CLI tooling for spec generation (JSON and YAML output)

CLI Quick Start

Generate an OpenAPI spec from your decorated function app:

# Install
pip install azure-functions-openapi

# Generate spec from a function app module (registers @openapi routes)
azure-functions-openapi generate --app function_app --title "My API" --format json

# Write to file with pretty-printing
azure-functions-openapi generate --app function_app --title "My API" --pretty --output openapi.json

# YAML output
azure-functions-openapi generate --app function_app --format yaml --output openapi.yaml

Pass module:variable when the FunctionApp instance has a non-default name:

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

See the CLI Guide for all options and CI integration examples.

Installation

pip install azure-functions-openapi

Your Function App dependencies should include:

azure-functions
azure-functions-openapi

Quick Start

import json

import azure.functions as func

from azure_functions_openapi.decorator import openapi
from azure_functions_openapi.openapi import get_openapi_json, get_openapi_yaml
from azure_functions_openapi.swagger_ui import render_swagger_ui


app = func.FunctionApp()


@app.function_name(name="http_trigger")
@app.route(route="http_trigger", auth_level=func.AuthLevel.ANONYMOUS, methods=["POST"])
@openapi(
    summary="Greet user",
    route="/api/http_trigger",
    method="post",
    request_body={
        "type": "object",
        "properties": {"name": {"type": "string"}},
        "required": ["name"],
    },
    response={
        200: {
            "description": "Successful greeting",
            "content": {
                "application/json": {
                    "schema": {
                        "type": "object",
                        "properties": {"message": {"type": "string"}},
                    }
                }
            },
        }
    },
    tags=["Example"],
)
def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
    data = req.get_json()
    name = data.get("name", "world")
    return func.HttpResponse(
        json.dumps({"message": f"Hello, {name}!"}),
        mimetype="application/json",
    )

@app.function_name(name="openapi_json")
@app.route(route="openapi.json", auth_level=func.AuthLevel.ANONYMOUS, methods=["GET"])
def openapi_json(req: func.HttpRequest) -> func.HttpResponse:
    return get_openapi_json(
        title="Sample API",
        description="OpenAPI document for the Sample API.",
    )


@app.function_name(name="openapi_yaml")
@app.route(route="openapi.yaml", auth_level=func.AuthLevel.ANONYMOUS, methods=["GET"])
def openapi_yaml(req: func.HttpRequest) -> func.HttpResponse:
    return get_openapi_yaml(
        title="Sample API",
        description="OpenAPI document for the Sample API.",
    )


@app.function_name(name="swagger_ui")
@app.route(route="docs", auth_level=func.AuthLevel.ANONYMOUS, methods=["GET"])
def swagger_ui(req: func.HttpRequest) -> func.HttpResponse:
    return render_swagger_ui()

Run locally with Azure Functions Core Tools:

func start

Demo

The representative hello example shows the full outcome of adopting this library:

• You annotate an Azure Functions v2 HTTP handler with @openapi.
• The package generates a real OpenAPI document for that route.
• The same route is rendered in Swagger UI for browser-based inspection.

Generated Spec Result

The generated OpenAPI file is captured as a static preview from the same example run, so the README shows the actual document produced by the representative function.

Swagger UI Result

The web preview below is generated from the same representative example and captured automatically from the rendered Swagger UI page produced by that example flow.

Documentation

• Full docs: yeongseon.github.io/azure-functions-openapi
• Smoke-tested examples: examples/
• Installation Guide
• Usage Guide
• API Reference
• CLI Guide

Ecosystem

• azure-functions-validation — Request and response validation
• azure-functions-logging — Structured logging
• azure-functions-doctor — Diagnostic CLI
• azure-functions-scaffold — Project scaffolding
• azure-functions-python-cookbook — Recipes and examples

Disclaimer

This project is an independent community project and is not affiliated with, endorsed by, or maintained by Microsoft.

Azure and Azure Functions are trademarks of Microsoft Corporation.

License

MIT