# Setting up Swagger UI in Next.js

This guide explains how to set up Swagger UI in a Next.js application using route groups.

## Directory Structure

The recommended directory structure for Swagger documentation:

```
app/
  (swagger)/           # Route group for swagger-related pages
    swagger/          # Actual swagger route
      page.tsx       # Swagger UI component
```

## Installation

1. Add Swagger UI dependencies to your project:

```json
{
  "dependencies": {
    "swagger-ui-react": "^5.12.0",
    "swagger-ui-dist": "^5.12.0"
  },
  "devDependencies": {
    "@types/swagger-ui-react": "^4.18.3"
  }
}
```

2. Install webpack style loaders for handling Swagger UI CSS:

```bash
pnpm add -D style-loader css-loader
```

## Next.js Configuration

Create or update `next.config.js` to handle Swagger UI CSS:

```javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['swagger-ui-react'],
  webpack: (config) => {
    config.module.rules.push({
      test: /\.css$/,
      use: ['style-loader', 'css-loader'],
    });
    return config;
  },
};

module.exports = nextConfig;
```

## Swagger UI Component

Create `app/(swagger)/swagger/page.tsx`:

```typescript
"use client";

import { useEffect } from 'react';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

export default function SwaggerPage() {
  useEffect(() => {
    document.title = 'API Documentation - ShortURL Analytics';
  }, []);

  const swaggerConfig = {
    openapi: '3.0.0',
    info: {
      title: 'Your API Title',
      version: '1.0.0',
      description: 'API documentation',
      contact: {
        name: 'API Support',
        email: 'support@example.com',
      },
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT',
      },
    },
    // ... your API configuration
  };

  return (
    <div className="container mx-auto px-4 py-8">
      <div className="mb-8">
        <h1 className="text-3xl font-bold mb-2">API Documentation</h1>
        <p className="text-gray-600">
          Explore and test the API endpoints using the interactive documentation below.
        </p>
      </div>
      <SwaggerUI spec={swaggerConfig} />
    </div>
  );
}
```

## Best Practices

1. **Route Groups**: Use route groups `(groupname)` to organize related pages without affecting the URL structure.

2. **API Documentation**:
   - Add detailed descriptions for all endpoints
   - Include parameter descriptions and constraints
   - Define response schemas
   - Document error responses
   - Use appropriate data formats (UUID, URI, etc.)
   - Group related endpoints using tags

3. **Swagger Configuration**:
   - Add contact information
   - Include license details
   - Set appropriate servers configuration
   - Define required fields
   - Add parameter validations (min/max values)

## Common Issues

1. **Route Conflicts**: Avoid parallel routes that resolve to the same path. For example, don't have both `app/swagger/page.tsx` and `app/(group)/swagger/page.tsx` as they would conflict.

2. **CSS Loading**: Make sure to:
   - Import Swagger UI CSS
   - Configure webpack in `next.config.js`
   - Use the `"use client"` directive as Swagger UI is a client-side component

3. **React Version Compatibility**: Be aware of potential peer dependency warnings between Swagger UI React and your React version. You might need to use `--legacy-peer-deps` or adjust your React version accordingly.

## Accessing the Documentation

After setup, your Swagger documentation will be available at `/swagger` in your application. The UI provides:
- Interactive API documentation
- Request/response examples
- Try-it-out functionality
- Schema definitions
- Error responses

## Maintenance

Keep your Swagger documentation up-to-date by:
- Updating the OpenAPI specification when adding or modifying endpoints
- Maintaining accurate parameter descriptions
- Keeping example values relevant
- Updating response schemas when data structures change