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