Expense-tracker-api — Frontend Test Client, Interactive Docs & Demo Frontend

This repository contains a set of frontends and documentation you can drop into your Expense Tracker API (Java backend) to:

• Explore the API interactively (Swagger UI / OpenAPI).
• Use a compact Test Client (single-file static app) to call endpoints and inspect responses.
• See the API "in action" with a simple demo frontend that lists and creates expenses.
• A complete OpenAPI (v3) specification that documents endpoints, request/response schemas and error responses.

Notes

• These frontends are static and require only a static file server (or can be opened directly in a browser for most setups). For CORS-restricted backends you may need to run each frontend via a simple static server (e.g., npx http-server or python -m http.server).
• Configure the backend base URL and Authorization (Bearer token) inside each frontend UI.

What you get in this package

• openapi.yaml — Full OpenAPI v3 spec for the Expense Tracker API (endpoints, schemas, status codes, errors).
• docs/swagger-ui/index.html — Interactive documentation using Swagger UI that loads openapi.yaml.
• test-client/index.html — Standalone Test Client to call endpoints, set headers, view responses.
• demo-frontend/index.html — Simple "production-like" frontend that shows expenses, and a form to create a new expense.
• postman_collection.json — Postman collection (optional) generated from the OpenAPI spec.

Quick start (static files)

1. Serve files with a simple server (recommended):
   • Using Node: npx http-server -c-1 .
   • Using Python 3: python -m http.server 8000
2. Open:
   • Interactive docs: http://localhost:8080/docs/swagger-ui/ (or /docs/swagger-ui/index.html)
   • Test client: http://localhost:8080/test-client/index.html
   • Demo frontend: http://localhost:8080/demo-frontend/index.html

OpenAPI / interactive docs

• The OpenAPI spec (openapi.yaml) documents endpoints, responses and error shapes.
• Swagger UI (docs/swagger-ui) loads the spec and provides a full API explorer where you can:
  • See endpoints, required params, example requests/responses.
  • Try operations by supplying a Bearer token and clicking "Execute".

Supported endpoints (documented)

• POST /auth/register — register new user
• POST /auth/login — login and receive JWT token
• GET /expenses — list expenses (supports paging, filtering by category/date)
• POST /expenses — create an expense
• GET /expenses/{id} — get expense by id
• PUT /expenses/{id} — update expense
• DELETE /expenses/{id} — delete expense
• GET /categories — list categories
• POST /categories — create category
• GET /stats/monthly — monthly summary (group totals by month)

Errors & status codes

• 200 OK, 201 Created, 204 No Content for successful operations.
• 400 Bad Request — validation errors; response includes errors array.
• 401 Unauthorized — missing or invalid JWT.
• 403 Forbidden — action not permitted.
• 404 Not Found — resource not found.
• 500 Internal Server Error — server error.

Files (overview)

• openapi.yaml — OpenAPI v3 spec (single source of truth).
• docs/swagger-ui/index.html — Swagger UI (loads openapi.yaml).
• test-client/index.html — Interactive Test Client (choose endpoint, fill form, send request).
• demo-frontend/index.html — Demo UI to view/create expenses.
• postman_collection.json — Postman collection.

How to adapt to your backend

• Update the "Base URL" in the frontends to point to your running Java backend (e.g., http://localhost:8080/api).
• If your backend prefixes endpoints differently, either:
  • Edit openapi.yaml and update the servers section.
  • Or update the Javascript BASE_URL variable inside test-client/index.html and demo-frontend/index.html.

Security / Auth

• The API uses Bearer JWT in Authorization header. Use the Login endpoint (/auth/login) to get a token, then paste it in the Test Client or Swagger UI "Authorize" modal.

Examples

• Example create expense payload: { "title": "Coffee", "amount": 3.75, "currency": "USD", "date": "2026-01-15", "categoryId": "e3b0c442-... (uuid)", "notes": "Morning coffee" }

Contributions

• These files are intentionally frontend-agnostic (static) so you can run them without a build step. If you'd like a React/Vue/Angular version, tell me which framework and I’ll scaffold it.

Support

• If you paste your actual backend base URL or the real routes (if they differ), I can adapt the OpenAPI file and frontends to match exactly.

Enjoy exploring your Expense Tracker API!