Swagger UI Setup

Swagger UI Setup for API Testing #

Swagger UI is pre-configured with automatic authentication for local development and Coder workspaces.

Quick Start #

  1. Start the development environment

    mise run dev

  2. Access Swagger UI

    • Local: http://localhost:8001
    • Coder: https://swagger-internal--dev--{workspace}--{owner}.coder.internal.gotofu.com

  3. Test APIs immediately - Authentication credentials are pre-filled! Click “Authorize” to verify.

What’s Pre-Configured #

All authentication headers are automatically injected:

  • Cloudflare Access - Auto-injected silently (CF-Access-Client-Id, CF-Access-Client-Secret)
  • Admin Key - Pre-filled in Authorize dialog (can be overridden)
  • Clerk User ID - Pre-filled from .config.yaml test credentials
  • Clerk Org ID - Pre-filled from .config.yaml test credentials
  • Coder Workspace URL - Automatically detected and set as default server

Authentication #

Click the “Authorize” button to see pre-filled values:

X-BonsAI-Admin-Key: [auto-filled from .env]
X-BonsAI-Clerk-User-Id: [auto-filled from .config.yaml]
X-BonsAI-Clerk-Organization-Id: [auto-filled from .config.yaml]

You can override any value by editing the field and clicking “Authorize”.

Configuration Files #

Authentication values are loaded from:

  • .env - Contains BONSAPI_ADMIN_KEY (from Doppler)
  • .config.yaml - Contains test Clerk credentials under test section: 
    test:
  clerk_user_id: user_2tU2uWZWPobyhGgNj6QGaZvJjl0
  clerk_org_id: org_2yG5SsBiMlSrwDJVBpofU0u8nR5

These are automatically set by override-coder-env.sh when running mise run dev.

Using Different Credentials (Optional) #

To use your own Clerk credentials instead of test credentials:

  1. Update .config.yaml with your credentials:

    test:
  clerk_user_id: your_clerk_user_id
  clerk_org_id: your_clerk_org_id

  2. Restart the containers:

    docker compose down swagger-ui-internal
docker compose up -d swagger-ui-internal

Troubleshooting #

Issue: Getting 401 or 403 errors

  • Verify credentials are pre-filled by clicking “Authorize”
  • Check that mise run dev completed successfully
  • Ensure .config.yaml contains test credentials

Issue: Can’t connect to API

  • In Coder: Ensure the server dropdown shows “Current Coder Workspace”
  • Local: Select http://localhost:8080 as the server

Issue: Credentials not pre-filled

  • Run ./tools/coder/scripts/override-coder-env.sh .env manually
  • Restart Swagger UI: docker compose restart swagger-ui-internal

Advanced: External Webhooks #

To test webhook APIs with external integrations:

  1. Start ngrok tunnel:

    mise run webhook

  2. Update .env:

    BONSAPI_EXTERNAL_HOST=your-tunnel-url.ngrok-free.app

  3. Restart services:

    docker compose restart bonsapi

Architecture #

The Swagger UI setup uses:

  • Docker containers - swagger-ui-internal, swagger-editor, swagger-api (mockoon)
  • Dynamic URL injection - Coder workspace URL detected at runtime
  • Template processing - Environment variables injected via entrypoint.sh
  • Separate interceptor - Authentication headers in interceptor.js (survives codegen)

See tools/swagger/entrypoint.sh and docker-compose.yml for implementation details.