OpenAPI

TableCraft can automatically generate OpenAPI 3.0 specifications from your table configurations.

How It Works

1

Generate Spec from Config

import { generateOpenApiSpec } from '@tablecraft/engine';
import { orders } from './tablecraft.config';

const spec = generateOpenApiSpec(orders.toConfig());

console.log(JSON.stringify(spec, null, 2));

2

Serve as JSON Endpoint

Create an endpoint that serves the spec.

Next.js Example:

// app/api/docs/[table]/route.ts
import { generateOpenApiSpec } from '@tablecraft/engine';
import * as configs from '@/tablecraft.config';

export async function GET(
  request: Request,
  { params }: { params: { table: string } }
) {
  const config = configs[params.table];
  
  if (!config) {
    return Response.json({ error: 'Table not found' }, { status: 404 });
  }

  const spec = generateOpenApiSpec(config.toConfig());
  return Response.json(spec);
}

Access: GET /api/docs/orders

3

Combine Multiple Tables

Generate a unified spec for all your tables.

function generateFullSpec() {
  const baseSpec = {
    openapi: '3.0.3',
    info: { title: 'My API', version: '1.0.0' },
    paths: {},
  };

  // Merge all table specs
  for (const [name, config] of Object.entries(configs)) {
    const tableSpec = generateOpenApiSpec(config.toConfig());
    Object.assign(baseSpec.paths, tableSpec.paths);
  }

  return baseSpec;
}

Generated Spec Structure

Example Input

const orders = defineTable(ordersTable)
  .search('status', 'customerName')
  .options('status', [
    { value: 'pending', label: 'Pending' },
    { value: 'completed', label: 'Completed' },
  ])
  .aggregate('totalRevenue', 'sum', 'total')
  .exportable('csv', 'json')
  .access({ roles: ['admin', 'sales'] });

Generated Output (Snippet)

{
  "openapi": "3.0.3",
  "info": {
    "title": "orders API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/orders": {
      "get": {
        "summary": "List orders",
        "operationId": "listOrders",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 25, "maximum": 100 }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Comma-separated fields. Prefix with - for desc."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Search across: status, customerName"
          },
          {
            "name": "export",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["csv", "json"] }
          },
          {
            "name": "filter[status]",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string", "description": "Order ID" },
                          "total": { "type": "number" },
                          "status": { "type": "string" },
                          "customerName": { "type": "string" }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "page": { "type": "integer" },
                        "pageSize": { "type": "integer" },
                        "totalPages": { "type": "integer" }
                      }
                    },
                    "aggregations": {
                      "type": "object",
                      "properties": {
                        "totalRevenue": { "type": "number" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          { "bearerAuth": [] }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}

Use Cases

Swagger UI

Serve the spec and mount Swagger UI:

// app/api-docs/page.tsx
'use client';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

export default function ApiDocs() {
  return <SwaggerUI url="/api/docs" />;
}

Client Gen

Postman

What Gets Included

✅ Automatically Generated

• Paths: One per table (/api/{tableName})

• Query Parameters: Pagination, Sorting, Filtering, Search, Export

• Response Schema: data[], meta, aggregations

• Security: Bearer auth (if access is configured)

❌ Not Included

• POST/PUT/DELETE: Only GET endpoints (TableCraft is read-only)

• Nested includes: Doesn't document nested relations

• Raw SQL columns: Included but type may be generic