from fastapi import FastAPI, HTTPException, Query
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class PaymentRequest(BaseModel):
    """Request body for initiating a payment."""
    amount: float  # Payment amount in USD
    currency: str  # ISO 4217 currency code (USD, EUR, GBP)
    idempotency_key: str  # Unique key to prevent duplicate charges
    metadata: Optional[dict] = None  # Custom key-value pairs (max 5KB)

class PaymentResponse(BaseModel):
    """Response after payment processing."""
    transaction_id: str  # Unique identifier for this transaction
    status: str  # PENDING, COMPLETED, FAILED
    amount: float  # Amount charged in requested currency
    timestamp: str  # ISO 8601 timestamp of transaction

@app.post("/payments", response_model=PaymentResponse)
async def create_payment(request: PaymentRequest) -> PaymentResponse:
    """
    Process a payment using Stripe.

    This endpoint initiates a payment charge against the authenticated user's
    payment method. Idempotency keys prevent duplicate charges if the request
    is retried.

    Args:
        request: PaymentRequest containing amount, currency, and idempotency_key

    Returns:
        PaymentResponse with transaction_id and status

    Raises:
        HTTPException(400): Invalid currency or amount format
        HTTPException(409): Idempotency key already used with different amount
        HTTPException(422): Payment method declined or insufficient funds

    Example:
        ```bash
 curl -X POST http://localhost:8000/payments \
 -H "Content-Type: application/json" \
 -d '{"amount": 99.99, "currency": "USD", "idempotency_key": "unique-123"}'
        ```

    Rate limit: 100 requests per minute
    Authentication: Bearer token required
    """
    # Implementation details...
    pass

import ast
import anthropic
import json

def extract_function_docs(python_file_path: str) -> list[dict]:
    """Extract docstrings and type hints from Python file."""
    with open(python_file_path, 'r') as f:
        tree = ast.parse(f.read())

    functions = []
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            docstring = ast.get_docstring(node) or "No documentation"
            args = [arg.arg for arg in node.args.args]
            functions.append({
                "name": node.name,
                "docstring": docstring,
                "args": args,
                "line": node.lineno
            })
    return functions

def generate_api_docs(function_docs: list[dict], format: str = "markdown") -> str:
    """Use Claude to generate formatted API documentation."""
    client = anthropic.Anthropic()

    prompt = f"""Convert these extracted function docstrings into professional {format} API documentation.
Include request/response examples, error codes, and rate limits where applicable.

Functions:
{json.dumps(function_docs, indent=2)}

Generate {format} that would appear in an API reference guide."""

    message = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=2048,
        messages=[{"role": "user", "content": prompt}]
    )
    return message.content[0].text

# Usage
docs = extract_function_docs("api.py")
markdown = generate_api_docs(docs, format="markdown")
print(markdown)

#!/usr/bin/env python3
"""
Automated API documentation generator.
Extracts comments from FastAPI app and generates OpenAPI spec.
"""

import ast
import json
from typing import Any
import anthropic
import yaml

class APIDocGenerator:
    def __init__(self, api_file: str):
        self.api_file = api_file
        self.client = anthropic.Anthropic()

    def extract_endpoints(self) -> list[dict[str, Any]]:
        """Extract FastAPI endpoint definitions and docstrings."""
        with open(self.api_file, 'r') as f:
            content = f.read()

        tree = ast.parse(content)
        endpoints = []

        for node in ast.walk(tree):
            if isinstance(node, ast.FunctionDef):
                # Look for decorators like @app.post, @app.get
                decorators = [
                    d.attr if hasattr(d, 'attr') else str(d)
                    for d in node.decorator_list
                ]
                if any('app.' in str(d) for d in decorators):
                    endpoints.append({
                        "function": node.name,
                        "docstring": ast.get_docstring(node),
                        "decorators": decorators,
                        "args": [arg.arg for arg in node.args.args]
                    })

        return endpoints

    def generate_openapi_spec(self, endpoints: list[dict[str, Any]]) -> dict:
        """Use Claude to generate OpenAPI spec from endpoints."""
        message = self.client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=4096,
            messages=[
                {
                    "role": "user",
                    "content": f"""Generate an OpenAPI 3.0.3 specification (valid YAML) from these FastAPI endpoints.
Include detailed schemas, examples, error responses, and security definitions.

Endpoints:
{json.dumps(endpoints, indent=2)}

Return ONLY valid YAML (no markdown code blocks, no explanations)."""
                }
            ]
        )

        spec_yaml = message.content[0].text
        return yaml.safe_load(spec_yaml)

    def save_openapi_yaml(self, spec: dict, output_file: str = "openapi.yaml"):
        """Save OpenAPI spec to YAML file."""
        with open(output_file, 'w') as f:
            yaml.dump(spec, f, default_flow_style=False, sort_keys=False)
        print(f"OpenAPI spec saved to {output_file}")

    def generate_markdown_docs(self, endpoints: list[dict[str, Any]]) -> str:
        """Generate Markdown documentation from endpoints."""
        message = self.client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=2048,
            messages=[
                {
                    "role": "user",
                    "content": f"""Generate professional Markdown API documentation from these endpoints.
Include examples, parameter descriptions, and error codes.

Endpoints:
{json.dumps(endpoints, indent=2)}

Generate well-structured Markdown with sections for each endpoint."""
                }
            ]
        )
        return message.content[0].text

# Usage
if __name__ == "__main__":
    generator = APIDocGenerator("api.py")

    # Extract endpoints
    endpoints = generator.extract_endpoints()
    print(f"Found {len(endpoints)} endpoints")

    # Generate OpenAPI spec
    spec = generator.generate_openapi_spec(endpoints)
    generator.save_openapi_yaml(spec)

    # Generate Markdown docs
    markdown = generator.generate_markdown_docs(endpoints)
    with open("API_DOCS.md", "w") as f:
        f.write(markdown)
    print("Markdown docs saved to API_DOCS.md")

# Good - Claude can extract this
def transfer_funds(source_id: str, destination_id: str, amount: float):
    """
    Transfer funds between accounts.

    Args:
        source_id: Unique identifier of source account (must be active)
        destination_id: Unique identifier of destination account
        amount: Transfer amount in USD (min $0.01, max $1,000,000)

    Returns:
        Transfer confirmation with transaction ID and timestamp

    Raises:
        ValueError: Invalid account IDs or amount out of range
        RuntimeError: Insufficient funds or account frozen
    """

# Example in comment - AI extracts for docs
"""
curl -X POST /transfers \
  -H "Authorization: Bearer token" \
  -d '{"source_id": "acc_123", "destination_id": "acc_456", "amount": 50.00}'
"""

"""
Rate limit: 100 requests per minute per account
Authentication: Bearer token (JWT) required
Webhook events: transfer.completed, transfer.failed
"""