gru_emoney_token-factory/api/tools/swagger-ui/QUICKSTART.md

Swagger UI Quick Start Guide

Local Development

Option 1: Node.js (Recommended)

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

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

Option 2: Docker

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

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:

// 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