651ff4f7eb
- 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
127 lines
2.4 KiB
Markdown
127 lines
2.4 KiB
Markdown
# Swagger UI Quick Start Guide
|
|
|
|
## Local Development
|
|
|
|
### Option 1: Node.js (Recommended)
|
|
|
|
```bash
|
|
cd api/tools/swagger-ui
|
|
pnpm install
|
|
pnpm run dev
|
|
```
|
|
|
|
Visit: http://localhost:8080/api-docs
|
|
|
|
### Option 2: Docker
|
|
|
|
```bash
|
|
cd api/tools/swagger-ui
|
|
docker-compose up
|
|
```
|
|
|
|
Visit: http://localhost:8080/api-docs
|
|
|
|
## Features
|
|
|
|
### Interactive Documentation
|
|
- Browse all API endpoints
|
|
- View request/response schemas
|
|
- See example payloads
|
|
- Explore data models
|
|
|
|
### Try It Out
|
|
- Test API calls directly from the browser
|
|
- Set authentication tokens
|
|
- View real responses
|
|
- Debug API interactions
|
|
|
|
### Authentication Testing
|
|
- OAuth2 client credentials flow
|
|
- mTLS configuration
|
|
- API key testing
|
|
- Token persistence
|
|
|
|
### Export Options
|
|
- Download OpenAPI spec as JSON
|
|
- Download OpenAPI spec as YAML
|
|
- Share documentation links
|
|
|
|
## API Endpoints
|
|
|
|
The Swagger UI server provides:
|
|
|
|
- `GET /api-docs` - Interactive documentation
|
|
- `GET /openapi.json` - OpenAPI spec (JSON)
|
|
- `GET /openapi.yaml` - OpenAPI spec (YAML)
|
|
- `GET /health` - Health check
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
SWAGGER_PORT=8080 # Server port (default: 8080)
|
|
```
|
|
|
|
### Customization
|
|
|
|
Edit `src/index.ts` to customize:
|
|
- Swagger UI theme
|
|
- Default expansion level
|
|
- Supported HTTP methods
|
|
- OAuth2 redirect URL
|
|
|
|
## Integration with Main API
|
|
|
|
To integrate Swagger UI into the main REST API server:
|
|
|
|
```typescript
|
|
// In 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
|
|
|
|
### Standalone Server
|
|
|
|
Deploy as separate service:
|
|
- Lightweight Express server
|
|
- Serves only documentation
|
|
- Can be behind CDN
|
|
- No API dependencies
|
|
|
|
### Embedded in API
|
|
|
|
Include in main API server:
|
|
- Single deployment
|
|
- Shared authentication
|
|
- Live spec updates
|
|
- Integrated experience
|
|
|
|
## Troubleshooting
|
|
|
|
### OpenAPI Spec Not Loading
|
|
|
|
1. Check file path: `../../packages/openapi/v1/openapi.yaml`
|
|
2. Verify YAML syntax is valid
|
|
3. Check file permissions
|
|
|
|
### OAuth2 Not Working
|
|
|
|
1. Verify redirect URL matches configuration
|
|
2. Check CORS settings
|
|
3. Ensure OAuth2 server is accessible
|
|
|
|
### Styles Not Loading
|
|
|
|
1. Check network tab for 404s
|
|
2. Verify CDN is accessible
|
|
3. Check custom CSS syntax
|
|
|