InvoiceShelf API Docs

The static Swagger UI site served at api-docs.invoiceshelf.com — the public REST API reference for the InvoiceShelf v3 API.

It is a frozen, self-contained artifact: a pinned swagger-ui-dist plus a baked-in openapi.json, served by nginx. The OpenAPI spec itself is generated in the app repo (InvoiceShelf/InvoiceShelf, 3.x branch) with Scramble — no annotations, inferred from the app's FormRequests and API Resources.

How it fits together

InvoiceShelf (3.x branch)
  └─ release published  ──▶  .github/workflows/openapi.yml
                               php artisan scramble:export → public/openapi.json (committed)
                               └─ repository_dispatch: spec-updated ─┐
                                                                     ▼
this repo  ──▶  .github/workflows/build.yml
                 scripts/fetch-specs.sh   (pulls 3.x public/openapi.json)
                 docker build             (swagger-ui-dist + openapi.json + nginx)
                 push ghcr.io/invoiceshelf/api-docs:latest
                 └─ repository_dispatch: image-pushed ─┐
                                                        ▼
k8s-production-cluster  ──▶  update-images.yaml bumps the digest in
                              applications/invoiceshelf/api-docs-deployment.yaml
                              └─ ArgoCD syncs → api-docs.invoiceshelf.com

Files

File	Purpose
index.html	Swagger UI shell, loads openapi.json
openapi.json	The spec. Placeholder in git; overwritten at build time by fetch-specs.sh
Dockerfile	Pinned swagger-ui-dist + spec → nginx
default.conf	nginx config (gzip, cache headers)
scripts/fetch-specs.sh	Pulls the latest openapi.json from the app repo's 3.x branch
.github/workflows/build.yml	Build + push image, notify the cluster

Local preview

bash scripts/fetch-specs.sh                 # pull the latest spec (optional)
docker build -t api-docs .
docker run --rm -p 8080:80 api-docs         # open http://localhost:8080

Required CI secret

• CLUSTER_DISPATCH_PAT — a PAT with repo scope on ideologix/k8s-production-cluster, used to trigger the cluster's digest bump. If unset, the build still publishes the image; the cluster will pick it up on its 6-hourly fallback schedule.

Adding the v2 API later

The site is intentionally v3-only. To also document the v2 (master) API, Swagger UI's urls option renders a version dropdown — fetch both specs, name them openapi-v3.json / openapi-v2.json, and switch index.html from url: to urls: [...].