azure-functions-openapi 0.12.1

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

azure-functions-openapi

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

Scope

• Azure Functions Python v2 programming model
• Decorator-based func.FunctionApp() applications
• HTTP-triggered functions documented with @openapi
• Optional Pydantic schema generation (supports both Pydantic v1 and 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 generation and validation workflows

Demo

The representative hello_openapi 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.

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",
    request_body={
        "content": {
            "application/json": {
                "schema": {
                    "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

Documentation

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

License

MIT