Corentin
21ce2a94c7
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>
107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
# 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` |
|