Copy page

Backend

OpenAPI Documentation

OpenAPI Documentation

Relevant source files

The following files were used as context for generating this wiki page:

• infra/docker-compose.postgres.yml
• src/modules/auth/avatar-svg-generator.ts
• src/modules/customers/list-config.ts
• src/openapi/openapi.ts
• src/openapi/router.ts

The Primebrick API exposes its capabilities through a machine-readable OpenAPI 3.0.3 specification. This specification serves as the source of truth for the REST interface, facilitating client-side SDK generation, automated testing, and interactive documentation via tools like Swagger UI or Redoc.

Specification Delivery

The specification is maintained as a static object within the codebase and served dynamically via a dedicated Express router.

openApiRouter

The openApiRouter is responsible for mounting the documentation endpoint. It exposes the specification at a standard path used by frontend consumers and external integrators.

• Endpoint: /api/v1/openapi.json src/openapi/router.ts:6-8
• Implementation: The router uses a simple GET handler that returns the openapi object exported from the definition file src/openapi/router.ts:4-10.

Data Flow: Specification Serving

The following diagram illustrates how the OpenAPI specification is stored and served to a client.

OpenAPI Specification Delivery Flow

Code
graph TD
  subgraph "Codebase Space"
    [openapi_js] --> |"export const openapi"| [router_ts]
  end

  subgraph "Express Runtime"
    [router_ts] --> |"router.get('/api/v1/openapi.json')"| [Express_App]
  end

  [Client] --> |"HTTP GET /api/v1/openapi.json"| [Express_App]
  [Express_App] --> |"JSON Response"| [Client]

  style openapi_js stroke-dasharray: 5 5
  style router_ts stroke-dasharray: 5 5

Sources: src/openapi/openapi.ts:1-7, src/openapi/router.ts:1-10

Specification Structure

The specification defined in src/openapi/openapi.ts includes metadata, path definitions, and reusable component schemas.

Metadata

• Title: Primebrick API src/openapi/openapi.ts:4-4
• Version: 0.1.0 src/openapi/openapi.ts:5-5
• Spec Version: 3.0.3 src/openapi/openapi.ts:2-2

Key Path Groups

The API paths are organized by module. Each path includes parameters, request bodies (where applicable), and typed responses referencing the components/schemas section.

Path Pattern	Description	Key Operations
/api/v1/entities/customer/*	Customer Management	list, meta, create, detail
/api/v1/entities/organization/*	Organization Management	list, meta, create, detail
/api/v1/auth/*	Authentication	login, refresh, profile

Sources: src/openapi/openapi.ts:7-203

Schema Definitions and Entity Mapping

The components/schemas section provides the structure for the data objects exchanged with the API. These schemas map directly to the domain entities and UI configuration types.

Entity Metadata

The EntityMetaResponse schema describes the UI configuration for entities, including column visibility and searchability. This is driven by configuration files such as src/modules/customers/list-config.ts.

• Columns: Includes key, labelKey, type (text, badge, datetime, color), and boolean flags like sortable and filterable src/modules/customers/list-config.ts:14-37.
• Visibility: Defines which fields are hidden, notHideable, or notDisplayable for different view modes (table, cards) src/modules/customers/list-config.ts:3-12.

Search and Filter DSL

The OpenAPI spec defines a complex query language for the list endpoints via the filters parameter:

• Field: The column name to filter.
• Operator (op): Supports =, !=, <>, <, <=, >, >=, ILIKE, LIKE, IN, NOT IN, IS, IS NOT src/openapi/openapi.ts:43-43.
• Connector: AND or OR logic src/openapi/openapi.ts:45-45.

Entity-to-OpenAPI Mapping Diagram

Code
classDiagram
  class "src/modules/customers/list-config.ts" {
    CUSTOMER_LIST_COLUMNS
    CUSTOMER_SORT_KEYS
    CUSTOMER_FILTERABLE_KEYS
  }

  class "src/openapi/openapi.ts" {
    EntityMetaResponse
    EntityListResponseCustomer
    CustomerStatus
  }

  "src/modules/customers/list-config.ts" ..> "src/openapi/openapi.ts" : "Informs Schema Definition"
  "src/openapi/openapi.ts" --|> "Client SDK" : "Generates"

Sources: src/modules/customers/list-config.ts:70-130, src/openapi/openapi.ts:23-63

Client Integration

Clients should consume the specification to ensure type safety and consistent error handling.

Response Handling

Standard responses include:

• 200 OK: Successful retrieval (e.g., EntityListResponseCustomer src/openapi/openapi.ts:57-57).
• 201 Created: Successful resource creation (e.g., CustomerCreateResponse src/openapi/openapi.ts:80-80).
• 404 Not Found: Resource not identified by UUID src/openapi/openapi.ts:102-102.

Authentication Integration

The specification includes the /api/v1/auth/login endpoint which facilitates username/password authentication src/openapi/openapi.ts:203-205. While the backend uses Casdoor for identity management infra/docker-compose.postgres.yml:60-62, the OpenAPI spec provides the proxy interface for frontend applications.

Sources: src/openapi/openapi.ts:75-103, infra/docker-compose.postgres.yml:60-70

---