# Swagger Documentation - Complete Guide

## Overview

Full Swagger/OpenAPI documentation for the eMoney Token Factory API is available through an interactive Swagger UI server.

## Quick Start

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

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

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

### Option 2: Docker

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

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

### Option 3: Standalone HTML

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

**Output**: `static/standalone.html` (open directly in browser)

## Documentation Endpoints

When the server is running:

- **Interactive Docs**: http://localhost:8080/api-docs
- **OpenAPI JSON**: http://localhost:8080/openapi.json
- **OpenAPI YAML**: http://localhost:8080/openapi.yaml
- **Standalone HTML**: http://localhost:8080/standalone
- **Health Check**: http://localhost:8080/health

## Features

### 1. Complete API Coverage

All API endpoints documented:
- ✅ Token operations (deploy, mint, burn, clawback, force-transfer)
- ✅ Lien management (place, reduce, release, query)
- ✅ Compliance operations (set, freeze, query)
- ✅ Account-Wallet mappings
- ✅ Trigger management (ISO-20022 processing)
- ✅ Packet operations (generate, dispatch, acknowledge)
- ✅ Bridge operations (lock, unlock)

### 2. Interactive Testing

- **Try It Out**: Test any endpoint directly from the browser
- **Request Builder**: Fill in parameters and see request format
- **Response Viewer**: See actual API responses
- **Error Handling**: View error responses with reason codes

### 3. Authentication Support

- **OAuth2**: Test client credentials flow
- **mTLS**: Configure mutual TLS for adapters
- **API Key**: Set API keys for internal services
- **Token Persistence**: Tokens saved across page reloads

### 4. Schema Documentation

- **Data Models**: All request/response schemas
- **Enums**: All enum values (ReasonCodes, TriggerStates, Rails, etc.)
- **Examples**: Example payloads for each endpoint
- **Validation Rules**: Field requirements and constraints

### 5. Export Options

- **Download JSON**: Get OpenAPI spec as JSON
- **Download YAML**: Get OpenAPI spec as YAML
- **Share Links**: Share specific endpoint documentation
- **Embed**: Embed Swagger UI in other applications

## API Modules Documented

### Tokens Module
- Deploy new eMoney tokens
- Configure token policies
- Mint and burn operations
- Clawback and force transfer
- Query token metadata

### Liens Module
- Place liens on accounts
- Reduce lien amounts
- Release liens
- Query lien information
- Check encumbrance summaries

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

### Mappings Module
- Link accounts to wallets
- Unlink mappings
- Query account wallets
- Query wallet accounts

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

### ISO-20022 Module
- Submit inbound messages (from rails)
- Submit outbound messages (to rails)
- Message normalization
- Instruction ID tracking

### Packets Module
- Generate packets (PDF/AS4/Email)
- Dispatch packets
- Track acknowledgements
- Download packet files

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

## Usage Examples

### Testing Token Deployment

1. Navigate to `/tokens` endpoint
2. Click "Try it out"
3. Fill in token configuration:
   ```json
   {
     "name": "USD Wrapped",
     "symbol": "USDW",
     "decimals": 18,
     "issuer": "0x1234...",
     "defaultLienMode": "ENCUMBERED"
   }
   ```
4. Click "Execute"
5. View response with token address

### Testing Lien Placement

1. Navigate to `/liens` endpoint
2. Click "Try it out"
3. Fill in lien details:
   ```json
   {
     "debtor": "0xabcd...",
     "amount": "1000000000000000000",
     "priority": 1,
     "reasonCode": "DEBT_ENFORCEMENT"
   }
   ```
4. Click "Execute"
5. View response with lien ID

### Setting Authentication

1. Click "Authorize" button at top
2. Enter OAuth2 token in "Value" field
3. Click "Authorize"
4. Token will be used for all requests
5. Click "Logout" to clear

## Integration

### Embed in Main API Server

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

### Production Deployment

1. **Standalone Service**: Deploy as separate service
2. **CDN Distribution**: Serve via CDN for performance
3. **Embedded**: Include in main API server
4. **Static HTML**: Generate and serve static file

## Customization

### Change Port

```bash
export SWAGGER_PORT=9000
pnpm start
```

### Custom Theme

Edit `src/index.ts`:

```typescript
const swaggerOptions = {
  customCss: `
    .swagger-ui .info .title { 
      color: #your-brand-color; 
      font-family: 'Your Font';
    }
  `,
};
```

### Default Server

Set default API server:

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

## Troubleshooting

### Server Won't Start

- Check if port 8080 is available
- Verify OpenAPI spec path is correct
- Check YAML syntax is valid

### Spec Not Loading

- Verify `openapi.yaml` exists
- Check file permissions
- Validate YAML syntax

### Try It Out Fails

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

## Best Practices

1. **Keep Spec Updated**: Update OpenAPI spec as API changes
2. **Use Examples**: Provide realistic examples in spec
3. **Document Errors**: Include error response examples
4. **Test Regularly**: Use Try It Out to validate endpoints
5. **Share Links**: Share specific endpoint URLs with team

## Additional Resources

- [OpenAPI Specification](https://swagger.io/specification/)
- [Swagger UI Documentation](https://swagger.io/tools/swagger-ui/)
- [API Integration Cookbook](../docs/api/integration-cookbook.md)
- [Error Catalog](../docs/api/error-catalog.md)