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 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.

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