API Documentation (Swagger)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Outmanage API uses Swagger (OpenAPI 3.0.0) to provide interactive and comprehensive documentation for its logistics management system. This documentation covers all aspects of the system, including warehouse operations, product inventory, delivery orders, and AI-powered fleet verification. The implementation ensures that developers can test endpoints directly through the browser while maintaining a clear contract of data structures and security requirements.
Sources: src/config/swagger.ts:4-14, comprehensive-swagger-api.json:2-10
The documentation is split into two distinct versions: a comprehensive version that describes the entire system and an auto-generated version specifically focused on weighing operations. These are exposed via different routes in the Express application to cater to different integration needs.
Sources: src/index.ts:50-71
Documentation Architecture
The system employs two methods for generating and serving documentation: a static JSON definition for comprehensive coverage and a dynamic JSDoc-based approach for specific route modules.
Documentation Types
| Documentation Type | Route | Source | Scope |
|---|---|---|---|
| Comprehensive | /api-docs | comprehensive-swagger-api.json | All system entities (RBAC, Warehouses, Logistics, AI) |
| Weighing-Specific | /weighing-docs | src/config/swagger.ts | JSDoc annotations in routes and schemas |
Sources: src/index.ts:51-71, src/config/swagger.ts:38
Integration Flow
The following diagram illustrates how the documentation is integrated into the Express application:
The application serves these specifications using swagger-ui-express. The comprehensive spec is loaded directly from a JSON file, while the weighing-specific spec is generated by scanning ./src/routes/*.ts and ./src/schemas/*.ts.
Sources: src/index.ts:10-11, src/index.ts:51-71, src/config/swagger.ts:38
Security and Authentication
The API documentation defines a custom security scheme for authenticated requests. Unlike standard Bearer tokens, the system primarily uses a custom header for JWT validation.
Authentication Schemes
- OutmanageAuth: A custom
apiKeylocated in the header under the namex-outmanage-token. - bearerAuth: A standard HTTP Bearer scheme (JWT format) defined in the auto-generated specs.
Sources: comprehensive-swagger-api.json:17-22, src/config/swagger.ts:25-30
Token Flow
Core API Tags and Modules
The documentation is organized into functional tags that reflect the domain-driven design of the Outmanage system.
| Tag | Description |
|---|---|
| Authentication | User login, token refresh, and logout operations. |
| Users & Roles | RBAC management, including permissions and assignments. |
| Warehouses | Facility management and user-to-warehouse assignments. |
| Logistics | Delivery Orders and Shipment tracking. |
| Shipment Weighing | Specialized endpoints for bulk weighing and item distribution. |
| AI Integration | Vehicle plate verification using Google Gemini AI. |
Sources: comprehensive-swagger-api.json:188-244, CLAUDE.md:30-48
Data Models and Schemas
The documentation defines complex objects used across the system. All IDs utilize the UUID format.
Key Entity Schema (User)
{
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"email": { "type": "string", "format": "email" },
"name": { "type": "string" },
"roleId": { "type": "string", "format": "uuid" },
"warehouseId": { "type": "string", "format": "uuid", "nullable": true }
}
}
Sources: comprehensive-swagger-api.json:115-135
Shipment and Weighing Logic
The documentation details a specific "Bulk Weigh" process where weight is distributed across shipment items.
Implementation Details
- Server URL: The API documentation assumes a relative base URL (
/). - Version Tracking: The Swagger version is automatically synced with the project's
package.jsonversion. - UI Customization: The Swagger UI is configured with custom CSS to hide the top bar for a cleaner integration.
Sources: src/config/swagger.ts:2-10, src/index.ts:56, src/index.ts:66
Summary
The Swagger documentation for the Outmanage project serves as a bridge between the backend business logic and various consumers (Frontend, Postman, and Weighing Systems). By maintaining two levels of documentation—comprehensive for full system management and JSDoc-based for specialized operations—the project ensures technical accuracy and ease of integration for its complex logistics and AI verification features.