# azure-functions-openapi

> Generate OpenAPI specs and Swagger UI for Azure Functions HTTP handlers.

## Package Info

- PyPI: `pip install azure-functions-openapi`
- Version: 0.16.0
- Python: >=3.10, <3.15
- License: MIT
- Docs: https://yeongseon.github.io/azure-functions-openapi-python/
- Repository: https://github.com/yeongseon/azure-functions-openapi-python

## What It Does

Declarative OpenAPI documentation for Azure Functions v2. Attach metadata via
`@openapi()` decorator or programmatically. Generates OpenAPI 3.0/3.1 specs in JSON/YAML.
Renders Swagger UI with enterprise security headers (CSP, HSTS).

## Core API

- `@openapi(summary, description, ...)` — Decorator for HTTP handlers
- `register_openapi_metadata(path, method, ...)` — Programmatic metadata registration
- `clear_openapi_registry()` — Clear registry for fresh start
- `generate_openapi_spec(title, version, ...)` — Generate spec dict
- `get_openapi_json(title, version, ...)` — Generate OpenAPI JSON string
- `get_openapi_yaml(title, version, ...)` — Generate OpenAPI YAML string
- `render_swagger_ui(title, openapi_url, ...)` — Render Swagger UI HTML
- `OpenAPIOperationMetadata` — Type for operation metadata
- `OpenAPISpecConfigError` — Exception for configuration errors
- `OPENAPI_VERSION_3_0`, `OPENAPI_VERSION_3_1` — Version constants
- `scan_validation_metadata(app)` — Auto-discover @validate_http metadata and register in OpenAPI registry

## Quick Start

```python
from pydantic import BaseModel
import azure.functions as func
from azure_functions_openapi import openapi, generate_openapi_spec, get_openapi_json

class GreetRequest(BaseModel):
    name: str

app = func.FunctionApp()

@app.route(route="greet")
@openapi(
    summary="Greet a person",
    description="Returns a personalized greeting",
    request_model=GreetRequest,
)
def greet(req: func.HttpRequest) -> func.HttpResponse:
    body = GreetRequest.model_validate_json(req.get_body())
    return func.HttpResponse(f"Hello, {body.name}!")

# Expose OpenAPI spec
@app.route(route="openapi.json")
def openapi_spec(req: func.HttpRequest) -> func.HttpResponse:
    spec = get_openapi_json(title="My API", version="1.0.0")
    return func.HttpResponse(spec, mimetype="application/json")
```

## Documentation

- [Installation](https://yeongseon.github.io/azure-functions-openapi-python/installation/)
- [Usage Guide](https://yeongseon.github.io/azure-functions-openapi-python/usage/)
- [API Reference](https://yeongseon.github.io/azure-functions-openapi-python/api/)
- [CLI Guide](https://yeongseon.github.io/azure-functions-openapi-python/cli/)

## Ecosystem

Part of **Azure Functions Python DX Toolkit**:
- `azure-functions-langgraph` — LangGraph deployment
- `azure-functions-validation` — Request/response validation
- **azure-functions-openapi** — OpenAPI and Swagger UI
- `azure-functions-logging` — Structured logging
- `azure-functions-doctor` — Pre-deploy diagnostics
- `azure-functions-scaffold` — Project scaffolding
- `azure-functions-durable-graph` — Manifest-first graph runtime
