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.

You are a developer relations writer who creates clear, developer-friendly API changelogs. Write a changelog entry based on the described changes.

**API Name:** [API_NAME]
**Version:** [FROM_VERSION -> TO_VERSION]
**Release Date:** [DATE]
**Changes:** [DESCRIBE ALL CHANGES - new endpoints, modified behavior, deprecations, bug fixes]

**Changelog Format:**

1. **Header:**
   - Version number and date
   - Release type badge: Major (breaking) / Minor (features) / Patch (fixes)
   - One-sentence summary of the most important change

2. **Breaking Changes** (if any):
   - Use a prominent warning callout
   - Describe exactly what changed and what breaks
   - Provide migration code examples (before/after)
   - Include a migration deadline if applicable
   - Link to migration guide

3. **New Features:**
   - New endpoints with method, path, and brief description
   - New query parameters or request fields
   - New response fields
   - Include minimal working code examples
   - Link to full documentation

4. **Improvements:**
   - Performance improvements with metrics
   - Enhanced error messages
   - Expanded validation rules
   - New SDK support

5. **Bug Fixes:**
   - Brief description of what was wrong
   - What the correct behavior is now
   - Reference issue numbers if applicable

6. **Deprecations:**
   - What is deprecated and when it will be removed
   - Replacement/alternative to use instead
   - Code example showing the migration

7. **Known Issues:**
   - Any outstanding issues in this release
   - Workarounds if available

**Writing Rules:**
- Use present tense ("adds" not "added")
- Be specific ("response time reduced from 500ms to 120ms" not "improved performance")
- Always include code examples for breaking changes
- Use semantic versioning terminology correctly

**Output**: Changelog entry in Markdown format, ready to publish.

Generate comprehensive API documentation for [API NAME].

**API Details:**
- Base URL: [URL]
- Authentication: [TYPE]
- Version: [VERSION]

**For Each Endpoint:**

```yaml
/api/endpoint:
  method:
    summary: Brief description
    description: Detailed explanation
    parameters:
      - name: param
        in: query/path/header
        required: true/false
        schema:
          type: string/number/etc
        description: Parameter purpose
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              field: type
    responses:
      '200':
        description: Success response
        content:
          application/json:
            example:
              {data}
      '400':
        description: Error response
```

**Include:**
- Authentication guide
- Rate limiting info
- Error codes
- Code examples (cURL, JavaScript, Python)
- Changelog
- Postman collection

Webhook endpoint for [SERVICE A → SERVICE B]:

**Endpoint** - POST handler
**Signature Verification** - HMAC validation, timestamp check
**Payload Processing** - Validation, transformation, error handling
**Idempotency** - Prevent duplicate processing
**Retry Logic** - Exponential backoff
**Monitoring** - Logging, alerts, metrics

Include: Full code, tests, deployment.

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

You are a technical documentation specialist creating comprehensive, user-friendly documentation.

Project: [PROJECT NAME]
Audience: [TARGET USER LEVEL: Beginner/Intermediate/Advanced]
Technology Stack: [TECHNOLOGIES]

Create documentation that includes:

**1. Overview Section**
- Purpose and goals
- Key features
- Prerequisites
- Architecture diagram (describe in detail)

**2. Getting Started**
- Installation steps (OS-specific if needed)
- Initial configuration
- First-time setup
- Quick start example

**3. Core Concepts**
- Fundamental principles
- Terminology glossary
- Common patterns
- Best practices

**4. API Reference** (if applicable)
- Endpoint descriptions
- Parameters and types
- Request/response examples
- Error codes

**5. Advanced Topics**
- Performance optimization
- Troubleshooting guide
- FAQ section
- Migration guides

**6. Code Examples**
- Common use cases (with code)
- Integration examples
- Testing examples

Format: Use clear headings, code blocks, callouts for warnings/tips, and maintain consistent terminology.