photos/API_DOCUMENTATION.md

# API Documentation Setup Guide

## Overview

I've set up **automatic API documentation** using `next-swagger-doc` that stays in sync with your code changes. Here's how it works:

## ✅ What's Implemented

### 1. **Documentation Generator** (`src/lib/swagger.ts`)
- Automatically scans your API routes in `src/app/api/`
- Generates OpenAPI 3.0 spec from JSDoc comments
- Includes all schemas, examples, and descriptions

### 2. **Documentation Viewer** (`/api/docs/page`)
- Interactive Swagger UI interface
- Try-it-out functionality for testing endpoints
- Dark/light mode support

### 3. **API Endpoint** (`/api/docs`)
- Serves the generated OpenAPI spec as JSON
- Can be consumed by external tools

## 🚀 Usage

### Access Documentation
Visit `http://localhost:3000/api/docs/page` to see your interactive API documentation.

### Add Documentation to New Routes

Add JSDoc comments above your route handlers:

```typescript
/**
 * @swagger
 * /api/your-endpoint:
 *   post:
 *     summary: Brief description of what this endpoint does
 *     description: Detailed description with more context
 *     tags: [YourTag]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               param1: { type: 'string', description: 'Parameter description' }
 *               param2: { type: 'number', minimum: 0, maximum: 1 }
 *     responses:
 *       200:
 *         description: Success response
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 result: { type: 'string' }
 *       400:
 *         description: Bad request
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Error'
 */
export async function POST(request: NextRequest) {
  // Your route handler code
}
```

## 📋 Example Documentation

I've already documented the **batch classification endpoint** as an example:

```typescript
/**
 * @swagger
 * /api/classify/batch:
 *   post:
 *     summary: Batch classify photos using AI models
 *     description: Process multiple photos with AI classification using ViT for objects and optionally CLIP for artistic/style concepts.
 *     tags: [Classification]
 *     requestBody:
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/BatchClassifyRequest'
 *           examples:
 *             basic:
 *               summary: Basic batch classification
 *               value:
 *                 limit: 10
 *                 minConfidence: 0.3
 *                 onlyUntagged: true
 *             comprehensive:
 *               summary: Comprehensive mode with dual models
 *               value:
 *                 comprehensive: true
 *                 minConfidence: 0.05
 *                 maxResults: 25
 */
```

## 🎯 Benefits

### 1. **Always Up-to-Date**
- Documentation is generated from your actual code
- No separate docs to maintain
- Automatically reflects API changes

### 2. **Interactive Testing**
- Built-in "Try it out" functionality
- Test endpoints directly from documentation
- See real request/response examples

### 3. **Developer Experience**
- Comprehensive schemas and examples
- Clear parameter descriptions
- Error response documentation

### 4. **Integration Ready**
- Standard OpenAPI 3.0 format
- Can be imported into Postman, Insomnia
- Works with code generators

## 🔧 Extending Documentation

### Add More Route Documentation

For each API route, add JSDoc comments with:

1. **Summary**: One-line description
2. **Description**: Detailed explanation
3. **Tags**: Group related endpoints
4. **Parameters**: Query parameters, path parameters
5. **Request Body**: Expected input schema
6. **Responses**: All possible response codes and schemas
7. **Examples**: Real usage examples

### Custom Schemas

Define reusable schemas in `src/lib/swagger.ts`:

```typescript
components: {
  schemas: {
    YourCustomSchema: {
      type: 'object',
      properties: {
        id: { type: 'string', description: 'Unique identifier' },
        name: { type: 'string', description: 'Display name' }
      },
      required: ['id', 'name']
    }
  }
}
```

### Examples with Multiple Scenarios

```typescript
examples:
  basic_usage:
    summary: Basic usage
    value: { param: "value" }
  advanced_usage:
    summary: Advanced with all options
    value: { param: "value", advanced: true }
```

## 🎨 Customization

### Styling
- Documentation UI automatically matches your app's theme
- Supports dark/light mode switching

### Organization
- Use **tags** to group related endpoints
- Order endpoints by adding them to the `tags` array in swagger.ts

### Authentication
- Add authentication schemas when needed
- Document API keys, bearer tokens, etc.

## 📝 Next Steps

1. **Document Remaining Routes**: Add JSDoc comments to all your API endpoints
2. **Add Examples**: Include realistic request/response examples
3. **Test Documentation**: Use the interactive UI to verify all endpoints work
4. **Export for External Use**: Generate OpenAPI spec for Postman/other tools

## 🚨 Important Notes

- The documentation page is at `/api/docs/page` (not just `/api/docs`)
- Swagger UI requires client-side rendering, so it's in the `page.tsx` file
- The generator automatically scans all files in `src/app/api/` for JSDoc comments
- Restart the dev server after adding new documentation to see changes

Your API documentation will automatically stay in sync as you develop new features! 🎉