Draft documentation and action

Author: mr-fatalyst

.github/workflows/docs-deploy.yml

@@ -0,0 +1,44 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Install MkDocs
+      run: pip install mkdocs-material
+
+    - name: Build Documentation
+      run: |
+        mkdocs build -f docs/en/mkdocs.yml -d $(pwd)/site
+        mkdocs build -f docs/ru/mkdocs.yml -d $(pwd)/site/ru
+        mkdocs build -f docs/es/mkdocs.yml -d $(pwd)/site/es
+        mkdocs build -f docs/de/mkdocs.yml -d $(pwd)/site/de
+        mkdocs build -f docs/fr/mkdocs.yml -d $(pwd)/site/fr
+
+    - name: Ensure site exists
+      run: mkdir -p site
+
+    - name: Write CNAME
+      run: echo 'fastopenapi.fatalyst.dev' > site/CNAME
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./site

docs/de/TODO

@@ -0,0 +1,61 @@
+# Erweiterte Nutzung
+
+In diesem Abschnitt behandeln wir fortgeschrittene Themen wie die Architektur von FastOpenAPI, die Erweiterung auf neue Frameworks und die Anpassung des generierten Verhaltens oder der Dokumentation. Diese Informationen richten sich an Entwickler:innen, die FastOpenAPI tiefer verstehen, anpassen oder in nicht-standardisierte Umgebungen integrieren möchten.
+
+## Architekturüberblick
+
+Das Design von FastOpenAPI ist von FastAPI inspiriert, aber framework-unabhängig aufgebaut. Die Hauptkomponenten sind:
+
+- **BaseRouter**: Die zentrale Basisklasse, welche Routing, OpenAPI-Schema-Generierung und Verarbeitung von Requests/Responses kapselt. Sie ist nicht an ein spezifisches Framework gebunden.
+- **Framework-spezifische Router**: Subklassen von `BaseRouter`, z. B. `FlaskRouter`, `StarletteRouter` usw., die die Integration mit konkreten Frameworks übernehmen.
+- **Pydantic-Modelle**: FastOpenAPI nutzt Pydantic zur Definition, Validierung und Dokumentation von Datenstrukturen.
+- **OpenAPI-Generierung**: FastOpenAPI erstellt auf Basis von Metadaten (Routen, Parameter, Modelle) automatisch ein vollständiges OpenAPI-3.1-Schema. Dieses ist unter `/openapi.json` abrufbar.
+- **Dokumentationsrouten**: Über `/docs` (Swagger UI) und `/redoc` (ReDoc) stehen interaktive Dokumentationen zur Verfügung.
+
+## Ablauf eines Requests
+
+1. Eine Anfrage trifft auf die Route einer Anwendung (z. B. in Flask), die mit FastOpenAPI registriert wurde.
+2. Der Dekorator `@router.get/post/...` hat die Funktion registriert.
+3. Vor dem Funktionsaufruf führt FastOpenAPI:
+   - Extraktion von Pfadparametern (meist durch das Framework selbst),
+   - Validierung von Query-/Header-/Body-Parametern (via Pydantic),
+   - Fehlerbehandlung bei ungültigen Eingaben durch.
+4. Die Funktion wird mit validierten Parametern aufgerufen.
+5. Die Antwort wird je nach `response_model` serialisiert (validiert und in JSON umgewandelt).
+6. Im Fehlerfall (z. B. `ResourceNotFoundError`) wird eine JSON-Fehlermeldung erzeugt.
+7. Die Antwort wird durch das Framework zurückgegeben.
+
+## Erweiterung auf weitere Frameworks
+
+FastOpenAPI ist modular konzipiert. Wenn dein Framework nicht unterstützt wird, kannst du eine eigene Integration schreiben.
+
+### Vorgehen:
+
+- Erstelle eine neue Klasse, die `BaseRouter` erweitert.
+- Implementiere:
+  - Registrierung von Routen (z. B. `add_route()`),
+  - (Optional) Startlogik der App,
+  - Einbindung von `/docs`, `/redoc`, `/openapi.json`.
+
+### Hinweise:
+
+- Bestehende Implementierungen wie `FlaskRouter`, `StarletteRouter` etc. dienen als gute Vorlage.
+- Methoden wie `get_openapi_schema()` in `BaseRouter` sind wiederverwendbar.
+
+## Beispiel: Eigener Router
+
+Wenn du z. B. einen `MyCustomFrameworkRouter` erstellen willst:
+
+```python
+from fastopenapi.base_router import BaseRouter
+
+class MyCustomRouter(BaseRouter):
+    def add_route(self, path, method, handler):
+        # Framework-spezifische Logik
+        pass
+```
+
+Du kannst bestehende Methoden überschreiben oder Hooks hinzufügen.
+
+---
+

docs/de/docs/advanced/advanced_usage.md

@@ -0,0 +1,172 @@
+# API-Referenz
+
+In diesem Abschnitt findest du eine detaillierte Referenz zu den Klassen und Modulen von FastOpenAPI, inklusive Schnittstellen, Methoden und konkreter Anwendungsbeispiele.
+
+## Projektstruktur
+
+FastOpenAPI verwendet eine modulare Architektur:
+
+```
+fastopenapi/
+├── base_router.py
+└── routers/
+    ├── aiohttp.py
+    ├── falcon.py
+    ├── flask.py
+    ├── quart.py
+    ├── sanic.py
+    ├── starlette.py
+    └── tornado.py
+```
+
+---
+
+## BaseRouter
+
+**Beschreibung:** Abstrakte Basisklasse, die Routing-Logik, OpenAPI-Schema-Generierung und Validierungsverhalten kapselt. Wird von den Framework-spezifischen Routern geerbt.
+
+### Wichtige Methoden
+
+- `__init__(...)`
+- `get(path, **options)`: Registriert einen GET-Endpunkt.
+- `post(path, **options)`: Registriert einen POST-Endpunkt.
+- `put(path, **options)`: Registriert einen PUT-Endpunkt.
+- `patch(path, **options)`: Registriert einen PATCH-Endpunkt.
+- `delete(path, **options)`: Registriert einen DELETE-Endpunkt.
+- `include_router(other_router, prefix="")`: Ermöglicht das Einbinden anderer Router unter einem Präfix.
+- `generate_openapi_schema()`: Erzeugt das OpenAPI-Schema.
+
+### Attribute
+
+- `app`: Das verbundene Framework-Objekt.
+- `docs_url`, `redoc_url`, `openapi_url`: Endpunkte für die Dokumentation.
+- `title`, `description`, `version`: Metadaten für die OpenAPI-Dokumentation.
+
+---
+
+## Framework-Router
+
+Jedes unterstützte Framework hat einen eigenen Router, der von `BaseRouter` erbt:
+
+- **AioHttpRouter**
+- **FalconRouter**
+- **FlaskRouter**
+- **QuartRouter**
+- **SanicRouter**
+- **StarletteRouter**
+- **TornadoRouter**
+
+---
+
+## Subrouter verwenden
+
+Du kannst Routen modular strukturieren:
+
+```python
+api_v1 = <Framework>Router()
+
+@api_v1.get("/users")
+def users():
+    return [{"name": "Alice"}, {"name": "Bob"}]
+
+main_router = <Framework>Router(app=app)
+main_router.include_router(api_v1, prefix="/v1")
+```
+
+---
+
+## Fehlerbehandlung
+
+### Bibliotheksinterne Fehlerklassen
+
+```python
+from fastopenapi.error_handler import BadRequestError, ResourceNotFoundError
+
+@router.get("/validate")
+def validate_input(param: int):
+    if param < 0:
+        raise BadRequestError("Parameter muss positiv sein")
+
+@router.get("/items/{item_id}")
+def get_item(item_id: int):
+    item = db.get(item_id)
+    if item is None:
+        raise ResourceNotFoundError(f"Item {item_id} nicht gefunden")
+```
+
+### Fehlerbehandlung je Framework
+
+FastOpenAPI unterstützt auch Framework-eigene Fehler:
+
+#### AioHTTP
+
+```python
+from aiohttp import web
+
+@router.get("/notfound")
+def aiohttp_notfound():
+    raise web.HTTPNotFound(reason="Not Found")
+```
+
+#### Falcon
+
+```python
+import falcon
+
+@router.get("/notfound")
+async def falcon_notfound():
+    raise falcon.HTTPNotFound(title="Not Found", description="Falcon error")
+```
+
+#### Flask
+
+```python
+from flask import abort
+
+@router.get("/notfound")
+def flask_notfound():
+    abort(404, description="Flask error")
+```
+
+#### Quart
+
+```python
+from quart import abort
+
+@router.get("/notfound")
+async def quart_notfound():
+    abort(404, description="Quart error")
+```
+
+#### Sanic
+
+```python
+from sanic import NotFound
+
+@router.get("/notfound")
+async def sanic_notfound():
+    raise NotFound()
+```
+
+#### Starlette
+
+```python
+from starlette.exceptions import HTTPException
+
+@router.get("/notfound")
+async def starlette_notfound():
+    raise HTTPException(status_code=404, detail="Not Found")
+```
+
+#### Tornado
+
+```python
+from tornado.web import HTTPError
+
+@router.get("/notfound")
+async def tornado_notfound():
+    raise HTTPError(status_code=404, reason="Not Found")
+```
+
+---
+

docs/de/docs/advanced/api_reference.md

@@ -0,0 +1,77 @@
+# Changelog
+
+Alle bedeutenden Änderungen an FastOpenAPI werden in dieser Datei dokumentiert.
+
+## [0.5.0] – Unveröffentlicht
+
+### Hinzugefügt
+- **AioHttpRouter** zur Integration mit dem AIOHTTP-Framework (async-Unterstützung).
+- Klassencache für Pydantic-Model-Schemas zur Leistungsverbesserung (vermeidet wiederholte Generierung von JSON Schema).
+- `response_errors`-Parameter für Routen-Dekoratoren, um Fehlerrückgaben in OpenAPI zu dokumentieren.
+- Modul `error_handler` für standardisierte Fehlerantworten (stellt Fehlerklassen wie `BadRequestError`, `ResourceNotFoundError` usw. bereit).
+- Unterstützung einfacher Python-Typen (`int`, `float`, `bool`, `str`) als `response_model`.
+
+## [0.4.0] – 20.03.2025
+
+### Hinzugefügt
+- Unterstützung für **ReDoc UI** (verfügbar unter `/redoc`).
+- **TornadoRouter** für das Tornado-Framework.
+
+### Geändert
+- Alle Tests überarbeitet zur Verbesserung der Abdeckung und Zuverlässigkeit.
+
+### Behoben
+- Fehlercode bei internen Fehlern geändert: von 422 auf 500, gemäß HTTP-Standards.
+
+### Entfernt
+- `add_docs_route` und `add_openapi_route` Methoden aus `BaseRouter` entfernt – Dokumentationsrouten werden jetzt automatisch hinzugefügt.
+
+## [0.3.1] – 15.03.2025
+
+### Behoben
+- Fehler beim Import von Routern ohne installiertes Framework (Abfangen von `ModuleNotFoundError`).
+
+## [0.3.0] – 15.03.2025
+
+### Hinzugefügt
+- **QuartRouter** für das Quart-Framework (async).
+- Erste Dokumentation (Einführung und Grundbeispiele) im Repository.
+
+### Geändert
+- Vereinfachter Import: jetzt `from fastopenapi.routers import YourRouter`.
+
+### Behoben
+- Query-Parameter über Pydantic-Modelle in GET-Routen werden nun korrekt erkannt und genutzt.
+
+## [0.2.1] – 12.03.2025
+
+### Behoben
+- Serialisierung von Antworten: `_serialize_response` konvertiert BaseModel jetzt korrekt in ein dict vor JSON.
+- Fehler im `DataLoader` bei leeren Daten beseitigt.
+- Zusätzliche Tests für obige Fälle hinzugefügt.
+- Diese Changelog-Datei (`CHANGELOG.md`) hinzugefügt.
+
+## [0.2.0] – 11.03.2025
+
+### Hinzugefügt
+- `resolve_endpoint_params` in `BaseRouter` implementiert zur Parameterauswertung (path, query, body).
+- `prefix`-Support in `include_router` zur Gruppierung von Routen.
+- `status_code`-Support in Dekoratoren (Default-Statuscode setzen).
+
+### Geändert
+- Refactoring aller Router-Implementierungen zur Vereinheitlichung und Reduzierung von Redundanz.
+
+### Entfernt
+- `register_routes` aus Starlette-Implementierung entfernt (veraltet durch Refactoring).
+
+## [0.1.0] – 01.03.2025
+
+### Hinzugefügt
+- Erste Veröffentlichung von FastOpenAPI.
+- Grundfunktionalität implementiert:
+  - Basisrouter-Klassen
+  - Unterstützung für Falcon, Flask, Sanic, Starlette
+  - OpenAPI-Schema-Generierung über Pydantic v2
+  - Parameter- und Body-Validierung
+- README und einfache Beispiele hinzugefügt.
+- Erste Tests zur Schema-Generierung und Routenregistrierung integriert.