Metadata-Version: 2.4
Name: azure-functions-openapi-pydantic
Version: 1.0.0a2
Summary: Lightweight OpenAPI decorator for Azure Functions with Pydantic support
License: MIT
License-File: LICENSE
Keywords: azure,functions,openapi,pydantic,swagger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: azure-functions>=1.19.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Azure Functions OpenAPI with Pydantic

A lightweight, modern OpenAPI decorator for Azure Functions with full Pydantic support. Generate accurate API documentation with minimal code.

## Features

- 🎯 **Simple decorator syntax** - Just add `@openapi()` to your functions
- 📝 **Pydantic integration** - Define request/response models with validation
- 🔄 **Response envelope** - Standardized `{success, data, error}` format
- 🏗️ **Nested models** - Automatically expands nested Pydantic models in docs
- ⚡ **Blueprint support** - Works seamlessly with Azure Functions blueprints
- 📊 **Smart defaults** - Auto-generates HTTP status codes based on your endpoint

## Installation

```bash
pip install azure-functions-openapi-pydantic
```

## Quick Start

```python
from azure.functions import HttpRequest, HttpResponse, Blueprint
from pydantic import BaseModel, Field, EmailStr
from azfunc_openapi_pydantic import openapi, ApiResponse, OpenAPIBlueprint

# Define your models
class CreateUserRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr

class User(BaseModel):
    id: str
    name: str
    email: EmailStr
    created_at: str

# Create blueprint with OpenAPI support
api_bp = OpenAPIBlueprint()

# Decorate your function
@api_bp.route(route="users", methods=["POST"])
@openapi(request=CreateUserRequest, response=User)
def create_user(req: HttpRequest) -> HttpResponse:
    """Create a new user"""
    body = req.validated_body  # Validated Pydantic model attached by decorator
    
    user = User(
        id="usr_123",
        name=body.name,
        email=body.email,
        created_at="2025-01-01T00:00:00Z"
    )
    
    return ApiResponse.ok(user, status_code=201)
```

## Generate OpenAPI Spec & Docs

```python
from azfunc_openapi_pydantic import generate_openapi_spec, generate_swagger_ui
import json

@app.route(route="openapi.json", methods=["GET"])
def openapi_spec(req: HttpRequest) -> HttpResponse:
    spec = generate_openapi_spec(title="My API", version="1.0.0")
    return HttpResponse(json.dumps(spec, indent=2), mimetype="application/json")

@app.route(route="docs", methods=["GET"])
def swagger_ui(req: HttpRequest) -> HttpResponse:
    return generate_swagger_ui(title="My API Documentation")
```

## Response Envelope

All responses follow a consistent envelope format:

**Success:**
```json
{
  "success": true,
  "data": { /* your response model */ },
  "error": null
}
```

**Error:**
```json
{
  "success": false,
  "data": null,
  "error": "Error message"
}
```

## Decorator Options

```python
@openapi(
    request=RequestModel,      # Pydantic model for POST/PUT body
    response=ResponseModel,    # Pydantic model for response data
    params={"id": str},        # Query/path parameters
    tags=["Users"],            # OpenAPI tags
    summary="Custom summary",  # Override function docstring
    errors={404: "Not found"}  # Custom error responses
)
```

## Nested Models

Nested Pydantic models are automatically expanded in the OpenAPI spec:

```python
class Address(BaseModel):
    street: str
    city: str
    country: str = "US"

class UserProfile(BaseModel):
    user: User
    address: Address
    preferences: dict

@openapi(response=UserProfile)
def get_profile() -> HttpResponse:
    # OpenAPI spec will show full nested structure
    ...
```

## Examples

Check out the [examples/](examples/) directory for a complete working Azure Functions app demonstrating:

- Full CRUD operations
- Request validation and error handling  
- Nested models and complex data structures
- Pagination and query parameters
- OpenAPI spec generation
- Swagger UI integration

To run the example:

```bash
cd examples
pip install -r requirements.txt
func start
```

Then visit `http://localhost:7071/api/docs` for interactive API documentation.

## License

MIT

