# Swagger UI Quick Start Guide

## Local Development

### Option 1: Node.js (Recommended)

```bash
cd api/tools/swagger-ui
pnpm install
pnpm run dev
```

Visit: http://localhost:8080/api-docs

### Option 2: Docker

```bash
cd api/tools/swagger-ui
docker-compose up
```

Visit: http://localhost:8080/api-docs

## Features

### Interactive Documentation
- Browse all API endpoints
- View request/response schemas
- See example payloads
- Explore data models

### Try It Out
- Test API calls directly from the browser
- Set authentication tokens
- View real responses
- Debug API interactions

### Authentication Testing
- OAuth2 client credentials flow
- mTLS configuration
- API key testing
- Token persistence

### Export Options
- Download OpenAPI spec as JSON
- Download OpenAPI spec as YAML
- Share documentation links

## API Endpoints

The Swagger UI server provides:

- `GET /api-docs` - Interactive documentation
- `GET /openapi.json` - OpenAPI spec (JSON)
- `GET /openapi.yaml` - OpenAPI spec (YAML)
- `GET /health` - Health check

## Configuration

### Environment Variables

```bash
SWAGGER_PORT=8080  # Server port (default: 8080)
```

### Customization

Edit `src/index.ts` to customize:
- Swagger UI theme
- Default expansion level
- Supported HTTP methods
- OAuth2 redirect URL

## Integration with Main API

To integrate Swagger UI into the main REST API server:

```typescript
// In api/services/rest-api/src/index.ts
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
import { join } from 'path';

const openapiSpec = YAML.load(join(__dirname, '../../packages/openapi/v1/openapi.yaml'));

app.use('/docs', swaggerUi.serve, swaggerUi.setup(openapiSpec));
```

## Production Deployment

### Standalone Server

Deploy as separate service:
- Lightweight Express server
- Serves only documentation
- Can be behind CDN
- No API dependencies

### Embedded in API

Include in main API server:
- Single deployment
- Shared authentication
- Live spec updates
- Integrated experience

## Troubleshooting

### OpenAPI Spec Not Loading

1. Check file path: `../../packages/openapi/v1/openapi.yaml`
2. Verify YAML syntax is valid
3. Check file permissions

### OAuth2 Not Working

1. Verify redirect URL matches configuration
2. Check CORS settings
3. Ensure OAuth2 server is accessible

### Styles Not Loading

1. Check network tab for 404s
2. Verify CDN is accessible
3. Check custom CSS syntax