sickn33/api-documentation-generator

Was macht api-documentation-generator?

Erstelle umfassende, entwicklerfreundliche API-Dokumentation aus Code, inklusive Endpunkten, Parametern, Beispielen und Best Practices.

Funktionen

• Automatische Extraktion: Analysiert Router, Controller und Endpunktdefinitionen aus Ihrem Code.
• Umfassende Details: Zeigt HTTP-Methoden, Pfade, Abfrageparameter, Pfadparameter, Anfragekörper und Antwortformate an.
• Beispielgenerierung: Erstellt automatisch Anfrage- und Antwortbeispiele basierend auf Typdefinitionen.
• Best Practices: Fügt Hinweise zu Authentifizierung, Paginierung, Fehlerbehandlung und Ratenbegrenzung hinzu.
• Mehrere Ausgabeformate: Unterstützt Markdown, OpenAPI 3.0 und benutzerdefiniertes HTML.

Unterstützte Plattformen

• Claude Code
• Cursor
• Codex CLI

Installation

1. Kopiere die Skill-Datei in dein Projektverzeichnis:

   cp -r sickn33/api-documentation-generator /pfad/zu/deinem/projekt/.skills/
   

2. Stelle sicher, dass die Konfiguration in .skills/config.yml vorhanden ist (siehe unten).

Konfiguration

Erstelle oder bearbeite .skills/config.yml:

skills:
  - name: sickn33/api-documentation-generator
    config:
      languages: ["javascript", "python", "java"]
      frameworks: ["express", "fastapi", "spring-boot"]
      outputFormat: "markdown"
      includeExamples: true

Verwendung

Führe den folgenden Befehl in deinem Projekt aus:

skill generate-docs [Pfad_zum_Code] -o [Ausgabepfad]

Beispiel:

skill generate-docs ./src -o ./docs/api.md

Optionen

Parameter	Beschreibung	Standardwert
--input	Pfad zum Quellcode	./src
--output	Ausgabepfad für die Dokumentation	./docs/api.md
--format	Ausgabeformat (markdown, openapi, html)	markdown
--framework	Erwartetes Framework (optional)	Auto-Erkennung
--include-best-practices	Best Practices einfügen	true

Wie es funktioniert

1. Code-Analyse: Das Skill durchsucht den angegebenen Quellcode nach Endpunkt-Definitionen (z. B. app.get() in Express, @app.get() in FastAPI, @RequestMapping in Spring Boot).
2. Metadaten-Extraktion: Für jeden gefundenen Endpunkt werden Pfad, Methode, Parameter (Pfad, Abfrage, Header, Body) und Antwortformat extrahiert.
3. Beispiel-Generierung: Basierend auf Typen oder vorhandenen Tests werden realistische JSON-Beispiele generiert.
4. Best Practices: Automatisch angewandte Hinweise zu Authentifizierung, Paginierung, Fehlerbehandlung und Caching.
5. Dokumentation: Erzeugt eine strukturierte Markdown-Datei (oder OpenAPI/HTML) mit allen gesammelten Informationen.

Beispiele

Quellcode (Express.js)

// routes/users.js
const express = require('express');
const router = express.Router();

router.get('/users', async (req, res) => {
  const { limit, offset } = req.query;
  const users = await db.findUsers(limit, offset);
  res.json(users);
});

router.post('/users', async (req, res) => {
  const user = await db.createUser(req.body);
  res.status(201).json(user);
});

Generierte Dokumentation

# API-Endpunkte

## GET /users

- **Beschreibung**: Ruft eine Liste von Benutzern ab.
- **Parameter**:
  - `limit` (Abfrage, optional) – Maximale Anzahl zurückzugebender Benutzer.
  - `offset` (Abfrage, optional) – Anzahl der zu überspringenden Benutzer.
- **Antwort**: `200 OK` – Array von Benutzerobjekten.

## POST /users

- **Beschreibung**: Erstellt einen neuen Benutzer.
- **Anfragekörper**: Benutzerobjekt (JSON).
- **Antwort**: `201 Created` – Das erstellte Benutzerobjekt.

Vorteile

• Zeitersparnis: Kein manuelles Schreiben von Dokumentation.
• Konsistenz: Dokumentation bleibt stets mit dem Code synchron.
• Qualität: Integrierte Best Practices verbessern die Nutzbarkeit.
• Integration: Einfach in CI/CD-Pipelines integrierbar.

Lizenz

MIT