Troubleshooting Guide¶

This guide helps you diagnose and resolve common issues with azure-functions-openapi.

🚨 Common Issues¶

1. Import Errors¶

Problem: ModuleNotFoundError¶

ModuleNotFoundError: No module named 'azure_functions_openapi'

Solutions: 1. Install the package:

pip install azure-functions-openapi

Check virtual environment:

# Activate your virtual environment
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Install in the correct environment
pip install azure-functions-openapi

Verify installation:

pip list | grep azure-functions-openapi
python -c "import azure_functions_openapi; print('OK')"

Problem: Import from wrong module¶

# ❌ Wrong
from azure_functions_doctor import openapi

# ✅ Correct
from azure_functions_openapi.decorator import openapi

2. Decorator Issues¶

Problem: Decorator not working¶

@openapi(summary="Test")
def my_function(req):
    return func.HttpResponse("Hello")

Solutions: 1. Check decorator order:

# ✅ Correct order
@app.route(route="test", auth_level=func.AuthLevel.ANONYMOUS)
@openapi(summary="Test")
def my_function(req):
    return func.HttpResponse("Hello")

Verify function registration:

from azure_functions_openapi.decorator import get_openapi_registry

registry = get_openapi_registry()
print(f"Registered functions: {list(registry.keys())}")

Problem: Validation errors¶

ValueError: Invalid route path: <script>alert('xss')</script>

Solutions: 1. Use safe route paths:

# ❌ Dangerous
@openapi(route="<script>alert('xss')</script>")

# ✅ Safe
@openapi(route="/api/users")

Check parameter validation:

# ❌ Invalid parameters
@openapi(parameters="not_a_list")

# ✅ Valid parameters
@openapi(parameters=[
    {"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}
])

3. OpenAPI Generation Issues¶

Problem: Empty OpenAPI spec¶

{
  "openapi": "3.0.0",
  "info": {"title": "API", "version": "1.0.0"},
  "paths": {}
}

Solutions: 1. Check function registration:

from azure_functions_openapi.decorator import get_openapi_registry

registry = get_openapi_registry()
if not registry:
    print("No functions registered with @openapi decorator")

Verify decorator usage:

# Make sure you're using the decorator correctly
@openapi(summary="Test function")
def test_function(req):
    return func.HttpResponse("OK")

Problem: Schema generation errors¶

RuntimeError: Failed to generate OpenAPI specification

Solutions: 1. Check Pydantic models:

# ❌ Invalid model
class InvalidModel:
    def __init__(self):
        self.name = "test"

# ✅ Valid Pydantic model
from pydantic import BaseModel

class ValidModel(BaseModel):
    name: str

Handle model errors gracefully:

try:
    spec = generate_openapi_spec()
except RuntimeError as e:
    print(f"OpenAPI generation failed: {e}")

4. Swagger UI Issues¶

Problem: Swagger UI not loading¶

Solutions: 1. Check route registration:

@app.route(route="docs", auth_level=func.AuthLevel.ANONYMOUS)
def swagger_ui(req):
    return render_swagger_ui()

Verify OpenAPI JSON endpoint:

@app.route(route="openapi.json", auth_level=func.AuthLevel.ANONYMOUS)
def openapi_json(req):
    return func.HttpResponse(get_openapi_json(), mimetype="application/json")

Check browser console for errors:
Open browser developer tools
Check for JavaScript errors
Verify network requests to /api/openapi.json

Problem: CSP (Content Security Policy) errors¶

Refused to load the script because it violates the following Content Security Policy directive

Solutions: 1. Use custom CSP policy:

custom_csp = "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net"
return render_swagger_ui(custom_csp=custom_csp)

Disable CSP for development:

# For development only
custom_csp = "default-src 'self' 'unsafe-inline' 'unsafe-eval'"
return render_swagger_ui(custom_csp=custom_csp)

5. CLI Tool Issues¶

Problem: CLI command not found¶

azure-functions-openapi: command not found

Solutions: 1. Reinstall the package:

pip install --upgrade azure-functions-openapi

Check installation:
```
pip show azure-functions-openapi
```

Use Python module syntax:

python -m azure_functions_openapi.cli --help

Problem: Spec validation errors¶

openapi-spec-validator openapi.json

Solutions: 1. Check OpenAPI spec format:

{
  "openapi": "3.0.0",
  "info": {
    "title": "API",
    "version": "1.0.0"
  },
  "paths": {}
}

Use correct file format:

# For JSON files
openapi-spec-validator spec.json

# For YAML files
openapi-spec-validator spec.yaml

🔍 Debugging Techniques¶

1. Enable Debug Logging¶

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('azure_functions_openapi')
logger.setLevel(logging.DEBUG)

2. Check Registry State¶

from azure_functions_openapi.decorator import get_openapi_registry

registry = get_openapi_registry()
print("Registered functions:")
for func_name, metadata in registry.items():
    print(f"  {func_name}: {metadata}")

3. Test OpenAPI Generation¶

from azure_functions_openapi.openapi import generate_openapi_spec

try:
    spec = generate_openapi_spec()
    print("OpenAPI spec generated successfully")
    print(f"Paths: {list(spec.get('paths', {}).keys())}")
except Exception as e:
    print(f"OpenAPI generation failed: {e}")
    import traceback
    traceback.print_exc()

📞 Getting Help¶

1. Check Documentation¶

2. Enable Verbose Logging¶

import logging
logging.basicConfig(level=logging.DEBUG)

3. Report Issues¶

When reporting issues, include:

Python version: python --version
Package version: pip show azure-functions-openapi
Error traceback: Full stack trace
Code example: Minimal reproducible example
Environment: OS, Azure Functions version, etc.

4. Community Support¶

🔧 Configuration¶

Environment Variables¶

# Debug mode
export AZURE_FUNCTIONS_OPENAPI_DEBUG=1

# Log level
export AZURE_FUNCTIONS_OPENAPI_LOG_LEVEL=DEBUG