# AcadeDoc API — Developer Documentation

## Swagger UI

Available at `/api/docs` when the server is running in dev or staging mode.

Production: disabled by default. Enable via `SWAGGER_ENABLED=true` env var.

```
http://localhost:3000/api/docs        # Swagger UI (interactive)
http://localhost:3000/api/docs-json   # OpenAPI 3 JSON spec
```

Access requires the workspace subdomain (or hostname middleware) to be set up correctly. The Swagger UI itself is public (no auth wall) but all endpoints inside it require a Bearer token.

## Authentication

All `/api/v1/*` endpoints require a Bearer JWT or `authToken` cookie from a successful login.

To authenticate in Swagger UI:
1. Open `/api/docs`
2. Click "Authorize" (top right)
3. Paste your JWT in the `BearerAuth` field
4. Click "Authorize" and close

To get a JWT via curl:

```bash
curl -X POST https://your-workspace.acadedoc.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'
```

Use the `token` field from the response.

## Example: Bearer authenticated request

```bash
export TOKEN="eyJ..."
export BASE="https://your-workspace.acadedoc.io"

curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/templates"
```

## Exporting the OpenAPI spec

```bash
curl -s http://localhost:3000/api/docs-json -o openapi.json
```

## Generating a TypeScript SDK client

Using `openapi-generator-cli` (requires Java or Docker):

```bash
# Install the CLI globally
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript-Fetch client
openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-fetch \
  -o ./sdk/acadedoc-client \
  --additional-properties=typescriptThreePlus=true,npmName=acadedoc-client,npmVersion=1.0.0

# Or using npx (no global install)
npx @openapitools/openapi-generator-cli generate \
  -i http://localhost:3000/api/docs-json \
  -g typescript-fetch \
  -o ./sdk/acadedoc-client
```

Supported generators: `typescript-fetch`, `typescript-axios`, `typescript-node`.

## Generating a Python SDK

```bash
openapi-generator-cli generate \
  -i openapi.json \
  -g python \
  -o ./sdk/acadedoc-python \
  --additional-properties=packageName=acadedoc_client
```

## Tags reference

| Tag | Controller prefix | Description |
|-----|------------------|-------------|
| `templates` | `/api/v1/templates` | Page templates CRUD + instantiate |
| `sync-blocks` | `/api/v1/sync-blocks` | Cross-page shared content blocks |
| `audit-log` | `/api/v1/audit-log` | Read-only workspace audit trail (admin) |
| `api-keys` | `/api/v1/api-keys` | Personal access tokens |
| `clipper` | `/api/v1/clipper` | Web clipper import + token management |
| `graph` | `/api/v1/graph` | Knowledge graph (nodes + edges) |
| `rbac` | `/api/v1/permissions`, `/api/v1/roles`, `/api/v1/users/:id/roles` | Role-based access control |
| `comments` | `/api/v1/page-comments`, `/api/v1/row-comments` | Page and Baserow row comments |
| `notifications` | `/api/v1/notifications`, `/api/v1/notification-preferences` | Notifications + preferences |
| `security` | `/api/v1/security` | OIDC/SSO configuration status |
| `backlinks` | `/api/v1/pages/:pageId/backlinks` | Bidirectional page backlinks |
| `slash-commands` | `/api/v1/slash-commands` | Custom editor slash commands |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SWAGGER_ENABLED` | unset | Set to `true` to enable Swagger UI in production |
| `NODE_ENV` | `development` | Swagger auto-enabled when not `production` |