# trojs/openapi-server architecture

> Architecture diagram of the GitHub repository trojs/openapi-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trojs/openapi-server
- Repository: https://github.com/trojs/openapi-server

## Overview

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: [`src/router.js`](https://github.com/trojs/openapi-server/blob/main/src/router.js) (Router setup), [`src/api.js`](https://github.com/trojs/openapi-server/blob/main/src/api.js) (Versioned API), [`src/express-callback.js`](https://github.com/trojs/openapi-server/blob/main/src/express-callback.js) (Controller callback), [`src/server.js`](https://github.com/trojs/openapi-server/blob/main/src/server.js) (Server setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server setup"]
  node_spec_loader["Spec loader<br/>[openapi.js]"]
  node_setup_server["Server setup<br/>[server.js]"]
end

subgraph group_routing["API routing"]
  node_api["Versioned API<br/>[api.js]"]
  node_router["Router setup<br/>[router.js]"]
  node_backend["OpenAPI backend"]
end

subgraph group_request["Request handling"]
  node_callback["Controller callback"]
  node_params["Parameter parsing<br/>[params.js]"]
  node_error_status["Error status mapping<br/>[error-status.js]"]
  node_request_validation["Request validation"]
  node_unauthorized["Unauthorized handler<br/>[unauthorized.js]"]
  node_not_found["Not-found handler<br/>[not-found.js]"]
  node_response_validation["Response validation"]
end

subgraph group_docs["Docs and integrations"]
  node_swagger["Swagger UI<br/>[api.js]"]
  node_api_docs["API specification docs<br/>[api.js]"]
  node_middleware["Express middleware<br/>[server.js]"]
end

node_caller(("API integrator"))
node_http(("HTTP client"))
node_controllers["Operation controllers"]
node_security["Custom security handlers"]
node_sentry{{"Sentry service"}}

node_caller -->|"loads specification"| node_spec_loader
node_caller -->|"configures API"| node_api
node_caller -->|"mounts APIs"| node_setup_server
node_spec_loader -->|"returns specification"| node_caller
node_http -->|"sends request"| node_setup_server
node_setup_server -->|"installs middleware"| node_middleware
node_setup_server -->|"mounts version"| node_api
node_setup_server -.->|"reports errors"| node_sentry
node_api -->|"sets up router"| node_router
node_api -->|"serves UI"| node_swagger
node_api -->|"serves specification"| node_api_docs
node_api -->|"dispatches request"| node_backend
node_router -->|"registers handlers"| node_backend
node_router -->|"registers operations"| node_callback
node_router -->|"registers validation"| node_request_validation
node_router -->|"registers response check"| node_response_validation
node_router -->|"registers auth handler"| node_unauthorized
node_router -->|"registers fallback"| node_not_found
node_router -->|"registers security"| node_security
node_backend -->|"dispatches operation"| node_callback
node_callback -->|"parses inputs"| node_params
node_callback -->|"invokes controller"| node_controllers
node_controllers -->|"returns result"| node_callback
node_callback -->|"maps errors"| node_error_status
node_backend -->|"handles response"| node_response_validation
node_response_validation -->|"sends response"| node_http

click node_spec_loader "https://github.com/trojs/openapi-server/blob/main/src/openapi.js"
click node_setup_server "https://github.com/trojs/openapi-server/blob/main/src/server.js"
click node_api "https://github.com/trojs/openapi-server/blob/main/src/api.js"
click node_router "https://github.com/trojs/openapi-server/blob/main/src/router.js"
click node_callback "https://github.com/trojs/openapi-server/blob/main/src/express-callback.js"
click node_params "https://github.com/trojs/openapi-server/blob/main/src/params.js"
click node_error_status "https://github.com/trojs/openapi-server/blob/main/src/error-status.js"
click node_request_validation "https://github.com/trojs/openapi-server/blob/main/src/handlers/request-validation.js"
click node_unauthorized "https://github.com/trojs/openapi-server/blob/main/src/handlers/unauthorized.js"
click node_not_found "https://github.com/trojs/openapi-server/blob/main/src/handlers/not-found.js"
click node_response_validation "https://github.com/trojs/openapi-server/blob/main/src/handlers/response-validation.js"
click node_swagger "https://github.com/trojs/openapi-server/blob/main/src/api.js"
click node_api_docs "https://github.com/trojs/openapi-server/blob/main/src/api.js"
click node_middleware "https://github.com/trojs/openapi-server/blob/main/src/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spec_loader,node_setup_server,node_http toneBlue
class node_api,node_router,node_backend toneAmber
class node_callback,node_params,node_error_status,node_request_validation,node_unauthorized,node_not_found,node_response_validation,node_caller,node_security toneMint
class node_swagger,node_api_docs,node_middleware toneRose
class node_controllers,node_sentry toneIndigo
```

## Components

### Server setup

- [Spec loader](https://github.com/trojs/openapi-server/blob/main/src/openapi.js): `src/openapi.js`
- [Server setup](https://github.com/trojs/openapi-server/blob/main/src/server.js): `src/server.js`

### API routing

- [Versioned API](https://github.com/trojs/openapi-server/blob/main/src/api.js): `src/api.js`
- [Router setup](https://github.com/trojs/openapi-server/blob/main/src/router.js): `src/router.js`
- **OpenAPI backend**

### Request handling

- [Controller callback](https://github.com/trojs/openapi-server/blob/main/src/express-callback.js): `src/express-callback.js`
- [Parameter parsing](https://github.com/trojs/openapi-server/blob/main/src/params.js): `src/params.js`
- [Error status mapping](https://github.com/trojs/openapi-server/blob/main/src/error-status.js): `src/error-status.js`
- [Request validation](https://github.com/trojs/openapi-server/blob/main/src/handlers/request-validation.js): `src/handlers/request-validation.js`
- [Unauthorized handler](https://github.com/trojs/openapi-server/blob/main/src/handlers/unauthorized.js): `src/handlers/unauthorized.js`
- [Not-found handler](https://github.com/trojs/openapi-server/blob/main/src/handlers/not-found.js): `src/handlers/not-found.js`
- [Response validation](https://github.com/trojs/openapi-server/blob/main/src/handlers/response-validation.js): `src/handlers/response-validation.js`

### Docs and integrations

- [Swagger UI](https://github.com/trojs/openapi-server/blob/main/src/api.js): `src/api.js`
- [API specification docs](https://github.com/trojs/openapi-server/blob/main/src/api.js): `src/api.js`
- [Express middleware](https://github.com/trojs/openapi-server/blob/main/src/server.js): `src/server.js`

### Other components

- **API integrator**
- **HTTP client**
- **Operation controllers**
- **Custom security handlers**
- **Sentry service**

## Connections

- 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