AI Prompts Library

Generate a REST API endpoint with the following spec:

Method: [GET / POST / PUT / DELETE]
Path: [/api/...]
Purpose: [WHAT IT DOES]
Auth: [JWT / API key / public]
Framework: [Express / FastAPI / Rails / Laravel]

Deliverables:
1. Route handler with input validation
2. OpenAPI/Swagger spec for this endpoint
3. TypeScript / Pydantic types for request and response
4. Two unit tests (happy path + invalid input)
5. cURL example for manual testing

Follow the existing project conventions for error handling, logging, and response shape.

You are a senior backend engineer specializing in Python FastAPI applications. Generate a complete, production-ready API module based on the requirements below.

**Module Requirements:**
- Resource name: [RESOURCE_NAME, e.g., 'users', 'products', 'orders']
- Database: [PostgreSQL/MongoDB/SQLite]
- ORM: [SQLAlchemy/Tortoise-ORM/Motor]
- Authentication: [JWT/OAuth2/API Key/None]
- Description: [WHAT_THIS_MODULE_DOES]

**Generate the following files:**

1. **models.py** - SQLAlchemy/Pydantic models:
   - Database model with proper column types, indexes, and constraints
   - Created_at, updated_at timestamps with timezone awareness
   - Soft delete support (is_deleted flag)
   - Relationship definitions

2. **schemas.py** - Pydantic v2 schemas:
   - CreateSchema (input validation for POST)
   - UpdateSchema (partial updates for PATCH, all fields Optional)
   - ResponseSchema (API output, excludes sensitive fields)
   - ListResponseSchema (paginated list with metadata)
   - Use Field() validators with examples in json_schema_extra

3. **router.py** - FastAPI router:
   - GET / - List with pagination, sorting, filtering
   - GET /{id} - Single resource with 404 handling
   - POST / - Create with 201 response and Location header
   - PATCH /{id} - Partial update
   - DELETE /{id} - Soft delete with 204 response
   - Include proper response_model, status_code, summary, description
   - Dependency injection for auth, database session

4. **service.py** - Business logic layer:
   - CRUD operations separated from route handlers
   - Transaction management
   - Custom exception classes
   - Event hooks (pre_create, post_create, etc.)

5. **tests/test_[resource].py** - Pytest tests:
   - Test each endpoint with valid and invalid data
   - Test authentication and authorization
   - Test edge cases (duplicate, not found, validation errors)
   - Use pytest fixtures and httpx AsyncClient

All code must include type hints, docstrings, and follow PEP 8.

You are an API design expert. Generate a complete OpenAPI 3.1 specification for the described API.

**API Details:**
- API Name: [API_NAME]
- Base URL: [BASE_URL]
- Version: [VERSION]
- Description: [WHAT_THE_API_DOES]
- Authentication: [Bearer JWT / API Key / OAuth2 / None]
- Resources: [LIST_YOUR_RESOURCES, e.g., users, products, orders]

**For each resource, generate:**

1. **Paths**: All CRUD endpoints plus any custom actions
   - Proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
   - Path parameters with descriptions
   - Query parameters for filtering, pagination, sorting
   - Request bodies with required/optional fields
   - All possible response codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 500)

2. **Schemas** (components/schemas):
   - Request schemas (Create, Update with partial fields)
   - Response schemas (single item, paginated list)
   - Error schema with code, message, details array
   - Enum types for status fields
   - Proper use of allOf, oneOf, anyOf for schema composition

3. **Security Schemes**: Define authentication with examples

4. **Tags**: Group endpoints logically with descriptions

5. **Examples**: Provide realistic request/response examples for every endpoint

6. **Pagination**: Use cursor-based or offset pagination with Link headers

7. **Rate Limiting**: Document rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining)

**Output Format:** Valid YAML OpenAPI 3.1 specification that can be imported directly into Swagger UI, Postman, or any OpenAPI-compatible tool. Include inline comments explaining design decisions.

Design comprehensive API error response:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Detailed explanation",
    "timestamp": "2025-10-02T02:00:00Z",
    "request_id": "uuid",
    "documentation_url": "https://docs.example.com/errors/ERROR_CODE",
    "field_errors": [
      {
        "field": "email",
        "message": "Invalid email format",
        "code": "INVALID_FORMAT"
      }
    ]
  }
}
```

**Error Categories**:
- 4xx Client Errors: Authentication, validation, not found
- 5xx Server Errors: Internal, service unavailable, timeout

**Best Practices**:
- Use consistent error codes
- Provide actionable messages
- Include request tracking
- Add documentation links
- Never expose sensitive data