# OpenAPI Documentation

# OpenAPI Documentation

<details>
<summary>Relevant source files</summary>

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

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

</details>



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**
```mermaid
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**
```mermaid
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]()

---