API-Dokumentations-Schreiber

Das Problem

API-Dokumentation fehlt entweder, ist automatisch ohne Kontext generiert oder wurde einmal geschrieben und nie aktualisiert. Entwickler, die Ihre API integrieren, verschwenden Stunden mit dem Erraten von Parameterformaten, dem Entschluesseln von Fehlerantworten und dem Reverse-Engineering des Verhaltens durch Versuch und Irrtum. Klare API-Docs mit realen Beispielen reduzieren die Integrationszeit von Tagen auf Stunden.

Der Prompt

Du bist ein erfahrener API-Technischer-Redakteur. Erstelle umfassende Dokumentation fuer folgende API-Endpunkte:

ENDPUNKTE:
[fuege deine Routendefinitionen, Controller-Code oder OpenAPI-Spezifikation hier ein]

BASIS-URL: [z.B. https://api.example.com/v1]
AUTH-METHODE: [z.B. Bearer Token, API-Key im Header, OAuth 2.0]

Dokumentiere fuer jeden Endpunkt:
1. **Methode & Pfad**: z.B. GET /users/:id
2. **Beschreibung**: Was dieser Endpunkt tut (ein Satz)
3. **Authentifizierung**: Erforderliche Auth-Stufe
4. **Parameter**: Tabelle mit Name, Position (Pfad/Query/Body), Typ, Pflicht, Beschreibung
5. **Request-Beispiel**: Vollstaendiger curl-Befehl oder fetch-Aufruf
6. **Erfolgsantwort**: Statuscode, Antwortkoerper mit realistischen Beispieldaten
7. **Fehlerantworten**: Alle moeglichen Fehlercodes mit Nachrichtenformat und wann sie auftreten
8. **Rate Limits**: Falls zutreffend

Formatiere als sauberes Markdown, geeignet fuer eine Dokumentationsseite.

Beispielausgabe

## GET /users/:id

Einen einzelnen Benutzer anhand seiner eindeutigen Kennung abrufen.

**Authentifizierung**: Bearer Token erforderlich (Scope: `users:read`)

### Parameter

| Name | In | Typ | Pflicht | Beschreibung |
|------|-----|-----|---------|--------------|
| id | Pfad | string (UUID) | ja | Eindeutige Benutzerkennung |
| fields | Query | string | nein | Kommagetrennte Felder zur Einbeziehung |

### Request

curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/v1/users/abc-123?fields=name,email

### 200 OK

{ "id": "abc-123", "name": "Max Mustermann", "email": "max@example.com" }

### Fehler

| Status | Code | Beschreibung |
|--------|------|--------------|
| 401 | UNAUTHORIZED | Fehlender oder ungueltiger Bearer Token |
| 404 | USER_NOT_FOUND | Kein Benutzer mit dieser ID vorhanden |
| 429 | RATE_LIMITED | Mehr als 100 Requests pro Minute ueberschritten |

Wann verwenden

Verwenden Sie diesen Skill beim Aufbau einer neuen API, bei der Einarbeitung externer Entwickler oder bei der Dokumentation einer bestehenden API, die nur im Code existiert. Fuettern Sie die KI mit Ihren Route-Dateien oder Controller-Code fuer die besten Ergebnisse. Ebenso nuetzlich bei der Umwandlung von internem API-Wissen in ein oeffentliches Entwicklerportal.

Profi-Tipps

• Fuegen Sie den tatsaechlichen Route-Handler-Code ein — die KI extrahiert Parametervalidierung, Fehlerbehandlung und Response-Strukturen direkt aus der Implementierung und erfasst Details, die Sie moeglicherweise vergessen wuerden.
• Fordern Sie eine OpenAPI-Spezifikation an — ergaenzen Sie “Erstelle zusaetzlich die OpenAPI-3.0-YAML fuer diese Endpunkte”, um maschinenlesbare Docs neben der menschenlesbaren Markdown-Version zu erzeugen.
• Dokumentieren Sie den Authentifizierungsfluss — ergaenzen Sie “Dokumentiere den vollstaendigen Auth-Flow vom Token-Erhalt bis zum authentifizierten Request”, damit Entwickler von Null zum funktionierenden API-Aufruf kommen.