How trojs/openapi-server works
This library builds versioned Express APIs from OpenAPI specifications: callers load a spec, provide operationId-matched controllers, configure an Api, and mount it with setupServer. Requests pass through OpenAPI routing and validation, parameter parsing, and controller execution before a validated HTTP response is sent. It also serves Swagger UI and specification documents, supports custom security handlers, and can enable Sentry. The main wiring is visible in sampled source; the specification loader’s internals are not sampled.
Main entry points: router.js Router setup · api.js Versioned API · express-callback.js Controller callback · server.js Server setup
Components 20
Server setup
- Spec loader
src/openapi.js - Server setup
src/server.js
API routing
- Versioned API
src/api.js - Router setup
src/router.js - OpenAPI backend
Request handling
- Controller callback
src/express-callback.js - Parameter parsing
src/params.js - Error status mapping
src/error-status.js - Request validation
src/handlers/request-validation.js - Unauthorized handler
src/handlers/unauthorized.js - Not-found handler
src/handlers/not-found.js - Response validation
src/handlers/response-validation.js
Docs and integrations
- Swagger UI
src/api.js - API specification docs
src/api.js - Express middleware
src/server.js
Other components
- API integrator
- HTTP client
- Operation controllers
- Custom security handlers
- Sentry service
Connections 26
- API integrator → Spec loader: loads specification
- API integrator → Versioned API: configures API
- API integrator → Server setup: mounts APIs
- Spec loader → API integrator: returns specification
- HTTP client → Server setup: sends request
- Server setup → Express middleware: installs middleware
- Server setup → Versioned API: mounts version
- Server setup → Sentry service: reports errors
- Versioned API → Router setup: sets up router
- Versioned API → Swagger UI: serves UI
- Versioned API → API specification docs: serves specification
- Versioned API → OpenAPI backend: dispatches request
- Router setup → OpenAPI backend: registers handlers
- Router setup → Controller callback: registers operations
- Router setup → Request validation: registers validation
- Router setup → Response validation: registers response check
- Router setup → Unauthorized handler: registers auth handler
- Router setup → Not-found handler: registers fallback
- Router setup → Custom security handlers: registers security
- OpenAPI backend → Controller callback: dispatches operation
- Controller callback → Parameter parsing: parses inputs
- Controller callback → Operation controllers: invokes controller
- Operation controllers → Controller callback: returns result
- Controller callback → Error status mapping: maps errors
- OpenAPI backend → Response validation: handles response
- Response validation → HTTP client: sends response