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

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)

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

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

Option 2: Docker

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

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

Option 3: Standalone HTML

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:

   {
     "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:

   {
     "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:

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

export SWAGGER_PORT=9000
pnpm start

Custom Theme

Edit src/index.ts:

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

Default Server

Set default API server:

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
• Swagger UI Documentation
• API Integration Cookbook
• Error Catalog