Add Swagger UI and dynamic OpenAPI generation

[amrohendawi]

Add interactive API docs (Swagger UI) at /api/docs, dynamically generate OpenAPI JSON at /api/v1/swagger.json from Flask routes, and fix token validation to use the User model's confirmation field.

Add Swagger UI with dynamic OpenAPI spec and token auth

Summary

Add an embedded Swagger UI at /api/docs/ and serve a dynamically generated OpenAPI 3.0 JSON at /api/v1/swagger.json. Enable an apiKey header security scheme named token so developers can Authorize in the UI and call protected endpoints.

What I changed (high level)

• Added Swagger UI registration and static assets for the UI.
• Implemented a dynamic OpenAPI generator that scans Flask's url_map for routes under /api/v1 and emits a minimal OpenAPI 3.0 document.
• Added a POST /api/v1/token endpoint to exchange credentials for an API token (in addition to the existing GET /api/v1/token).
• Added token header security scheme (token) to the generated spec so Authorize works.
• Fixed token validation to use the real model fields (email_confirmed_at / is_active) and added a User.confirmed compatibility property.

Files touched

• app/__init__.py — register Swagger UI blueprint
• app/api_v1/__init__.py — swagger.json endpoint (dynamic spec generator)
• app/api_v1/base.py — token endpoints
• app/models.py — User.confirmed compatibility property
• app/utils/decorators.py — token validation fix
• requirements.txt — add flask-swagger-ui dependency

How to test locally

1. Initialize DB schema (tables and default users):

python manage.py init_db

Or run via Docker Compose and initialize inside the container:

docker compose up -d --build
# then inside container:
# python manage.py init_db

2. Start the app in dev:

FLASK_ENV=development python flask_app.py

3. Open the UI:

Visit http://localhost:5000/api/docs/

4. Get a token:

POST credentials to POST /api/v1/token with JSON body:

{ "email": "admin@example.com", "password": "admin1234567" }

(or use GET /api/v1/token when logged in)

5. In Swagger UI, click Authorize and enter the token in the token field, then call protected endpoints.

Notes / Blockers

• I could not push the feature branch (feat/swagger-ui-token-fix) to the upstream repo due to a GitHub permission error (HTTP 403). You can:

  • Push from an account with write access, or
  • Fork and push the branch from your fork, then open a PR.

• The dynamic spec currently provides minimal operation descriptions and path/parameter scaffolding; request/response schemas can be enriched later.

• Ensure DB is initialized before testing token endpoints (otherwise requests return "no such table: users").

Suggested labels

• enhancement
• api
• docs