Summary
Two developer/operator-facing additions to improve onboarding and API discoverability:
1. Standalone SwaggerUI (docs/swagger/index.html)
A self-contained HTML page that provides interactive API documentation:
- Dark theme with Fortemi branding
- Configurable server URL — connect to any Fortemi instance (local or remote)
- Live health check indicator (connected/unreachable)
- Endpoint statistics bar — shows path count, endpoint count, HTTP method breakdown, schema count, tags, and API version at a glance
- Full SwaggerUI v5 with try-it-out enabled, filtering, request duration display, and persistent authorization
- URL parameter support —
?server=https://my-instance.com for bookmarkable links
- Loads spec from
/openapi.yaml which covers all 223 annotated endpoints across 18 tag groups
This complements the existing /docs endpoint (utoipa-swagger-ui) by providing a standalone page that can be served independently, used for offline reference, or customized without rebuilding the Rust binary.
2. Install Script (install.sh)
Single-command deployment for the Docker bundle:
curl -fsSL https://raw.githubusercontent.com/fortemi/fortemi/main/install.sh | bash
Features:
- Prerequisite checks — Docker, Compose v2, NVIDIA GPU + Container Toolkit
- Auto-installs Docker on Linux if missing
- GPU auto-detection with graceful CPU-only fallback
- Environment generation — creates
.env with sensible defaults
- Flags:
--no-gpu, --no-whisper, --no-gliner, --no-diarization, --domain, --port, --data-dir, --dry-run
- Health wait — polls
/health until API is ready
- Post-install summary — shows URLs, quick-start curl examples, MCP integration snippet
- Uninstall support —
--uninstall with optional data volume cleanup
Endpoint coverage verification
The OpenAPI spec (loaded by SwaggerUI) is generated at runtime by utoipa from 223 #[utoipa::path] annotations across:
crates/matric-api/src/main.rs — 186 annotations
crates/matric-api/src/handlers/*.rs — 37 annotations (archives, audio, chat, document_types, models, pke, provenance, vision)
All 18 OpenAPI tags are covered: Notes, Tags, Search, Jobs, OAuth, System, SKOS, Collections, Embeddings, Graph, Backup, Templates, Webhooks, Attachments, PKE, Provenance, Archives, DocumentTypes.
Files
| File |
Lines |
Purpose |
docs/swagger/index.html |
649 |
Standalone SwaggerUI with dark theme |
install.sh |
456 |
Single-command Docker bundle installer |
Summary
Two developer/operator-facing additions to improve onboarding and API discoverability:
1. Standalone SwaggerUI (
docs/swagger/index.html)A self-contained HTML page that provides interactive API documentation:
?server=https://my-instance.comfor bookmarkable links/openapi.yamlwhich covers all 223 annotated endpoints across 18 tag groupsThis complements the existing
/docsendpoint (utoipa-swagger-ui) by providing a standalone page that can be served independently, used for offline reference, or customized without rebuilding the Rust binary.2. Install Script (
install.sh)Single-command deployment for the Docker bundle:
curl -fsSL https://raw.githubusercontent.com/fortemi/fortemi/main/install.sh | bashFeatures:
.envwith sensible defaults--no-gpu,--no-whisper,--no-gliner,--no-diarization,--domain,--port,--data-dir,--dry-run/healthuntil API is ready--uninstallwith optional data volume cleanupEndpoint coverage verification
The OpenAPI spec (loaded by SwaggerUI) is generated at runtime by utoipa from 223
#[utoipa::path]annotations across:crates/matric-api/src/main.rs— 186 annotationscrates/matric-api/src/handlers/*.rs— 37 annotations (archives, audio, chat, document_types, models, pke, provenance, vision)All 18 OpenAPI tags are covered: Notes, Tags, Search, Jobs, OAuth, System, SKOS, Collections, Embeddings, Graph, Backup, Templates, Webhooks, Attachments, PKE, Provenance, Archives, DocumentTypes.
Files
docs/swagger/index.htmlinstall.sh