Skip to content

🛠️ Development

Working on the auth server itself.

📂 Repository layout

Path Purpose
main.py FastAPI app factory, environment wiring, lifespan, OpenAPI customization
jwt/ The auth routes package (router, get_current_user)
generate_spec.py Regenerates the committed OpenAPI spec
docs/api/ API reference (Swagger UI embed + openapi.json)
docs/lib/ Generated library reference (docforge)
docs/wiki/ This hand-written wiki
tests/ Async route tests against an in-memory Mongo mock

🔧 Setup

1
2
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt

Dependencies are installed from the private pip index (see requirements.txt and the Dockerfile). Core runtime packages:

  • py-jwt==0.0.4 — provides jwtlib (applications logic, models, security, introspection)
  • mongo-ops==0.1.3 — MongoDB persistence layer
  • fastapi, uvicorn, python-jose, passlib, bcrypt, pymongo

🧪 Tests

Run the suite (no network or Mongo required — an in-memory mock is used):

1
.venv/Scripts/pytest --asyncio-mode=auto

Coverage spans the full HTTP flow: register → login → wrong-password 401 → /me with and without a token → stateless logout.

📜 Regenerating the OpenAPI spec

The committed docs/api/openapi.json is produced offline:

1
2
set MONGO_HOST=127.0.0.1
python generate_spec.py

MONGO_HOST only needs to be set for the import; no connection is opened.

📝 Building documentation (docforge)

The site is generated by docforge and served per kind under site/{kind}:

1
2
3
4
5
doc-forge build \
  --api --openapi-spec docs/api/openapi.json \
  --mkdocs --wiki \
  --module jwt \
  --site-name "Aetoskia Auth Server"
  • --api renders openapi.json with Swagger UI.
  • --mkdocs renders the library reference from the jwt package docstrings (nested under docs/lib/jwt/, matching docforge.nav.yml).
  • --wiki builds this wiki.
  • Navigation layout is defined in docforge.nav.yml.

The jwt module is rendered without --module-is-source so the library output stays nested under docs/lib/jwt/, matching the committed docs/mkdocs.lib.yml nav.

Preview locally:

1
2
3
doc-forge serve --api
doc-forge serve --lib
doc-forge serve --wiki