Skip to content

Add standalone SwaggerUI page and single-command install script #9

@robit-man

Description

@robit-man

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions