Initial project setup: Add contracts, API definitions, tests, and documentation
- Add Foundry project configuration (foundry.toml, foundry.lock) - Add Solidity contracts (TokenFactory138, BridgeVault138, ComplianceRegistry, etc.) - Add API definitions (OpenAPI, GraphQL, gRPC, AsyncAPI) - Add comprehensive test suite (unit, integration, fuzz, invariants) - Add API services (REST, GraphQL, orchestrator, packet service) - Add documentation (ISO20022 mapping, runbooks, adapter guides) - Add development tools (RBC tool, Swagger UI, mock server) - Update OpenZeppelin submodules to v5.0.0
This commit is contained in:
defiQUG
278
api/tools/swagger-ui/SWAGGER_DOCS.md
Normal file
278
api/tools/swagger-ui/SWAGGER_DOCS.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user