1 lines (1 loc) · 5.61 KB

OpenAPI Quick Start Reference\n\n## 🚀 Quick Installation\n\n`bash\n# Install in all services\nfor service in api-gateway auth-service order-service delivery-service restaurant-service tracking-service; do\n cd services/$service && npm install && cd ../..\ndone\n`\n\n## 📚 Access Swagger UI\n\n| Service | URL |\n|---------|-----|\n| API Gateway | http://localhost:3000/api-docs |\n| Auth Service | http://localhost:3001/api-docs |\n| Order Service | http://localhost:3002/api-docs |\n| Restaurant Service | http://localhost:3003/api-docs |\n| Delivery Service | http://localhost:3004/api-docs |\n| Tracking Service | http://localhost:3005/api-docs |\n\n## 🔌 Using Service Clients\n\n### Initialize (once per service startup)\n`typescript\nimport { initializeServiceClients } from '../../../services/shared/serviceClients';\ninitializeServiceClients();\n`\n\n### Order Operations\n`typescript\nimport { orderServiceApi } from '../../../services/shared/serviceClients';\n\n// Create\nconst order = await orderServiceApi.createOrder({ customerId, restaurantId, items, totalAmount });\n\n// Retrieve\nconst order = await orderServiceApi.getOrder(orderId);\n\n// Cancel\nawait orderServiceApi.cancelOrder(orderId, 'Reason');\n`\n\n### Restaurant Operations\n`typescript\nimport { restaurantServiceApi } from '../../../services/shared/serviceClients';\n\n// Search\nconst restaurants = await restaurantServiceApi.searchRestaurants({ city, cuisine });\n\n// Get\nconst restaurant = await restaurantServiceApi.getRestaurant(restaurantId);\n\n// Menu\nconst menu = await restaurantServiceApi.getMenu(restaurantId);\n`\n\n### Delivery Operations\n`typescript\nimport { deliveryServiceApi } from '../../../services/shared/serviceClients';\n\n// Get partners\nconst partners = await deliveryServiceApi.getAvailablePartners({ city, vehicleType });\n\n// Assign\nconst assignment = await deliveryServiceApi.assignDelivery({ orderId, restaurantLocation, deliveryLocation });\n\n// Update status\nawait deliveryServiceApi.updateAssignmentStatus(assignmentId, 'in_transit', location);\n`\n\n### Tracking Operations\n`typescript\nimport { trackingServiceApi } from '../../../services/shared/serviceClients';\n\n// Get tracking\nconst tracking = await trackingServiceApi.getTracking(orderId);\n\n// Update\nawait trackingServiceApi.updateTracking(orderId, { status, location });\n`\n\n## 🔑 Environment Variables\n\n`bash\n# .env file (optional - defaults to localhost)\nAUTH_SERVICE_URL=http://auth-service:3001\nORDER_SERVICE_URL=http://order-service:3002\nRESTAURANT_SERVICE_URL=http://restaurant-service:3003\nDELIVERY_SERVICE_URL=http://delivery-service:3004\nTRACKING_SERVICE_URL=http://tracking-service:3005\nAPI_GATEWAY_URL=http://api-gateway:3000\n`\n\n## ❌ Replace These Old Patterns\n\n### Before: Direct axios\n`typescript\nconst response = await axios.post('http://localhost:3002/orders', data);\n`\n\n### After: Service client\n`typescript\nconst result = await orderServiceApi.createOrder(data);\n`\n\n### Before: Message queue\n`typescript\nawait publishEvent('order.created', { orderId });\n`\n\n### After: REST API\n`typescript\nawait orderServiceApi.createOrder(data);\n`\n\n## 📊 Common Patterns\n\n### Error Handling\n`typescript\ntry {\n const result = await orderServiceApi.createOrder(data);\n} catch (error) {\n if (error.response?.status === 400) {\n // Validation error\n } else if (error.response?.status === 404) {\n // Not found\n } else if (!error.response) {\n // Network error (already retried)\n }\n}\n`\n\n### Using in Middleware\n`typescript\napp.use(async (req, res, next) => {\n initializeServiceClients();\n next();\n});\n`\n\n### Async Calls\n`typescript\n// Parallel calls\nconst [restaurants, orders] = await Promise.all([\n restaurantServiceApi.searchRestaurants(filters),\n orderServiceApi.getOrder(orderId)\n]);\n`\n\n## ✅ Verification Checklist\n\n- [ ] All services have swagger-ui-express installed\n- [ ] Service clients initialized before use\n- [ ] Swagger UI loads at `/api-docs` for each service\n- [ ] Can make test requests via Swagger UI\n- [ ] Service-to-service calls use new clients\n- [ ] No more direct axios calls to other services\n- [ ] All services have openapi.ts file\n- [ ] Environment variables set correctly (if needed)\n\n## 🆘 Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Swagger UI 404 | Check service is running, import `setupSwagger` and `./openapi` |\n| Service not found | Verify URL in `shared/openapi/services.ts` |\n| Timeout errors | Increase timeout in `serviceClientFactory.createClient()` |\n| Auth errors | Verify JWT token is valid and set in headers |\n| CORS errors | Check service allows cross-origin requests |\n\n## 📦 Dependencies Added\n\n`json\n{\n \"swagger-ui-express\": \"^5.0.0\",\n \"swagger-jsdoc\": \"^6.2.8\"\n}\n`\n\n## 🔗 Resources\n\n- Full guide: `OPENAPI_MIGRATION_GUIDE.md`\n- Implementation details: `OPENAPI_IMPLEMENTATION_SUMMARY.md`\n- Service files: `services/*/src/openapi.ts`\n- Client library: `services/shared/serviceClients.ts`\n\n## 💡 Pro Tips\n\n1. Always initialize clients in service startup\n2. Use Swagger UI to test endpoints before coding\n3. Check status codes in error responses\n4. Monitor service logs for integration issues\n5. Use environment variables for non-local deployments\n6. Test service-to-service communication in staging\n\n## 🎯 Next: Remove Message Queues\n\nOnce REST APIs are working:\n1. Identify all message queue usages\n2. Replace with REST API calls\n3. Keep queue only for async notifications if needed\n4. Test thoroughly before removing dependencies\n