API-Dokumentation: Swagger/OpenAPI Endpoints vollständig dokumentieren #52

New issue

Open

opened 2026-03-30 19:57:05 +00:00 by David · 0 comments

David commented

2026-03-30 19:57:05 +00:00

Collaborator

Beschreibung

Alle FastAPI-Endpoints mit Response-Models, Descriptions und Examples ausstatten, sodass die automatisch generierte Swagger-Dokumentation (/docs) vollständig und nutzbar ist.

Hintergrund

FastAPI generiert automatisch Swagger UI unter /docs und ReDoc unter /redoc. Aktuell fehlen an den meisten Endpoints: Response-Models, Descriptions, Parameter-Descriptions und Examples. Die generierte Doku ist dadurch unbrauchbar für Entwickler die die API integrieren wollen.

Akzeptanzkriterien

Alle Endpoints haben response_model Parameter mit Pydantic-Model
Alle Endpoints haben summary und description
Alle Path/Query-Parameter haben description und example
Alle Error-Responses dokumentiert (400, 401, 403, 404, 500)
API ist in logische Tags gruppiert: Tickets, Pipeline, Repos, Auth, Settings
/docs zeigt vollständige, nutzbare API-Dokumentation

Technische Hinweise

Erweitern: backend/api/tickets.py — Response-Models und Descriptions
Erweitern: backend/api/pipeline.py — Response-Models und Descriptions
Erweitern: backend/api/repos.py — Response-Models und Descriptions
Erweitern: backend/main.py — API-Metadaten (title, description, version, tags)
Pydantic Response-Models evtl. in backend/schemas/ auslagern
Migration nötig: nein

Aufwand: M

## Beschreibung Alle FastAPI-Endpoints mit Response-Models, Descriptions und Examples ausstatten, sodass die automatisch generierte Swagger-Dokumentation (`/docs`) vollständig und nutzbar ist. ## Hintergrund FastAPI generiert automatisch Swagger UI unter `/docs` und ReDoc unter `/redoc`. Aktuell fehlen an den meisten Endpoints: Response-Models, Descriptions, Parameter-Descriptions und Examples. Die generierte Doku ist dadurch unbrauchbar für Entwickler die die API integrieren wollen. ## Akzeptanzkriterien - [ ] Alle Endpoints haben `response_model` Parameter mit Pydantic-Model - [ ] Alle Endpoints haben `summary` und `description` - [ ] Alle Path/Query-Parameter haben `description` und `example` - [ ] Alle Error-Responses dokumentiert (400, 401, 403, 404, 500) - [ ] API ist in logische Tags gruppiert: Tickets, Pipeline, Repos, Auth, Settings - [ ] `/docs` zeigt vollständige, nutzbare API-Dokumentation ## Technische Hinweise - Erweitern: `backend/api/tickets.py` — Response-Models und Descriptions - Erweitern: `backend/api/pipeline.py` — Response-Models und Descriptions - Erweitern: `backend/api/repos.py` — Response-Models und Descriptions - Erweitern: `backend/main.py` — API-Metadaten (title, description, version, tags) - Pydantic Response-Models evtl. in `backend/schemas/` auslagern - Migration nötig: nein ## Aufwand: M