gru_emoney_token-factory/docs/api/swagger-ui-guide.md

# Swagger UI Documentation Guide

## Overview

The Swagger UI provides interactive, browser-based documentation for the eMoney Token Factory API. It automatically generates documentation from the OpenAPI 3.1 specification.

## Accessing the Documentation

### Local Development

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

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

### Production

The Swagger UI can be:
- Deployed as a standalone service
- Embedded in the main API server
- Served via CDN
- Generated as static HTML

## Features

### 1. Interactive API Explorer

- **Browse Endpoints**: Navigate through all API endpoints organized by tags
- **View Schemas**: Explore request/response data models
- **See Examples**: View example payloads for each endpoint
- **Filter**: Search and filter endpoints by tag or keyword

### 2. Try It Out

- **Test API Calls**: Execute API requests directly from the browser
- **Set Parameters**: Fill in path, query, and body parameters
- **View Responses**: See real API responses with status codes
- **Debug**: Inspect request/response headers and bodies

### 3. Authentication

- **OAuth2**: Test OAuth2 client credentials flow
- **mTLS**: Configure mutual TLS for adapter endpoints
- **API Key**: Set API keys for internal services
- **Token Persistence**: Authorization tokens persist across page reloads

### 4. Schema Documentation

- **Data Models**: View all data structures with field descriptions
- **Enums**: See all possible enum values
- **Relationships**: Understand how models relate to each other
- **Examples**: View example JSON for each model

## Using the Documentation

### Finding an Endpoint

1. Use the search box to filter endpoints
2. Expand tags to see related endpoints
3. Click on an endpoint to see details

### Testing an Endpoint

1. Click "Try it out" button
2. Fill in required parameters
3. Click "Execute"
4. View the response below

### Setting Authentication

1. Click "Authorize" button at the top
2. Enter your OAuth2 token or API key
3. Click "Authorize"
4. Token will be used for all requests

### Exporting the Spec

- **JSON**: Visit `/openapi.json`
- **YAML**: Visit `/openapi.yaml`
- **Download**: Use the download button in Swagger UI

## Endpoint Categories

### Tokens
- Deploy new tokens
- Manage token policies
- Mint/burn operations
- Clawback and force transfer

### Liens
- Place liens on accounts
- Reduce or release liens
- Query lien information
- Check encumbrance

### Compliance
- Set compliance profiles
- Freeze/unfreeze accounts
- Manage risk tiers
- Set jurisdiction information

### Mappings
- Link accounts to wallets
- Query bidirectional mappings
- Manage provider connections

### Triggers
- Submit ISO-20022 messages
- Query trigger status
- Manage trigger lifecycle
- View trigger history

### ISO-20022
- Submit inbound messages
- Submit outbound messages
- Normalize messages
- Track message processing

### Packets
- Generate packets
- Dispatch packets
- Track acknowledgements
- Download packet files

### Bridge
- Lock tokens for cross-chain
- Unlock tokens with proofs
- Query lock status
- View supported corridors

## Best Practices

### For Developers

1. **Start with Examples**: Use the example payloads as starting points
2. **Test Locally**: Use Swagger UI to test before writing code
3. **Check Schemas**: Understand data models before integration
4. **Use Try It Out**: Validate your understanding of endpoints

### For Integration Teams

1. **Share Links**: Share specific endpoint URLs with team members
2. **Export Specs**: Download OpenAPI spec for code generation
3. **Document Issues**: Use Swagger UI to demonstrate API issues
4. **Validate Requests**: Use Try It Out to validate request formats

## Troubleshooting

### Endpoint Not Showing

- Check if endpoint is in OpenAPI spec
- Verify tag is correct
- Check for syntax errors in spec

### Try It Out Not Working

- Verify server is running
- Check CORS settings
- Ensure authentication is set
- Check network tab for errors

### Authentication Failing

- Verify token format
- Check token expiration
- Ensure correct OAuth2 flow
- Check server logs

## Integration

### Embed in Main API

Add to `api/services/rest-api/src/index.ts`:

```typescript
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));
```

### Standalone Deployment

Deploy as separate service:
- Lightweight and fast
- Can be behind CDN
- No API dependencies
- Easy to update

### Static HTML Generation

Generate standalone HTML file:

```bash
cd api/tools/swagger-ui
pnpm run generate:standalone
```

Output: `static/standalone.html` (can be opened directly in browser)

## Advanced Configuration

### Custom Theme

Edit `src/index.ts`:

```typescript
const swaggerOptions = {
  customCss: `
    .swagger-ui .info .title { color: #your-color; }
  `,
};
```

### Default Values

Set default server URL:

```typescript
swaggerOptions: {
  url: 'https://api.emoney.example.com/v1',
}
```

### OAuth2 Configuration

Configure OAuth2 redirect:

```typescript
swaggerOptions: {
  oauth2RedirectUrl: 'https://your-domain.com/oauth2-redirect.html',
}
```

## Support

For issues or questions:
- Check OpenAPI spec syntax
- Verify server configuration
- Review Swagger UI logs
- Consult Swagger UI documentation