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:

/**
 * @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:

/**
 * @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:

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

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! 🎉