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

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:

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:

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:

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

Default Values

Set default server URL:

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

OAuth2 Configuration

Configure OAuth2 redirect:

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