Corentin 21ce2a94c7 feat(acadedoc): add OpenAPI Swagger documentation for /api/v1/* — R5.3

Install @nestjs/swagger@^11.4.2 + nestjs-zod@^5.3.0. Bootstrap SwaggerModule
in main.ts with cleanupOpenApiDoc (dev/staging only; SWAGGER_ENABLED=true for
prod). Add @ApiTags, @ApiBearerAuth, @ApiOperation, @ApiResponse, @ApiParam,
@ApiQuery, @ApiBody decorators to all 16 acadenice /v1/* controllers.
Add swagger.spec.ts (8 tests green). Add docs/api-docs.md (SDK gen guide).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-08 15:36:14 +02:00

3.5 KiB

Raw Permalink Blame History

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:

Open /api/docs
Click "Authorize" (top right)
Paste your JWT in the BearerAuth field
Click "Authorize" and close

To get a JWT via curl:

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

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

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

Exporting the OpenAPI spec

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

Generating a TypeScript SDK client

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

# 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

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`

3.5 KiB Raw Permalink Blame History