AutoDoc: KI-generierte OpenAPI-Dokumentation aus C# ohne manuelle Annotationen

Die manuelle Pflege von API-Dokumentationen ist ein zeitraubender Fluch für viele .NET-Entwickler. Selbst kleine Nachlässigkeiten bei Attributen oder Kommentaren führen zu fehlerhaften Swagger-Dokumentationen, die nicht mehr dem tatsächlichen Code entsprechen. Doch was wäre, wenn eine KI diese Arbeit vollständig übernehmen könnte – ohne zusätzliche Annotationen, ohne XML-Kommentare und ohne manuelle Synchronisation? Das Projekt AutoDoc zeigt, wie lokale KI-Modelle wie Llama 3.2 automatisch valide OpenAPI 3.0.3-Spezifikationen aus rohem C#-Code generieren können.

Das Tool ist das Ergebnis einer persönlichen Frustration während eines Software-Praktikums. Damals wurde klar: Dokumentation wird oft vernachlässigt, weil sie als lästige Pflichtaufgabe gilt. AutoDoc ändert diese Dynamik, indem es die Dokumentation direkt aus dem Quellcode ableitet – und zwar ohne Vorbedingungen für den Entwickler.

Wie AutoDoc funktioniert: Drei Entwicklungsphasen zu einem fertigen Tool

Der Weg von einer simplen Idee zu einem vollwertigen Dokumentationsgenerator verlief in drei klar definierten Phasen. Jede Phase erweiterte die Funktionalität um entscheidende Aspekte – von einer lokalen Konsole bis hin zu einem browserbasierten Dienst, der ohne Setup auskommt.

Phase 1: Die Geburtsstunde als Konsolenanwendung

Alles begann mit einer simplen Frage: Kann ein KI-Modell rohen C#-Code analysieren und daraus eine vollständige OpenAPI-Dokumentation erstellen – ohne jede manuelle Annotation? Die Antwort fiel positiv aus. Das Ergebnis war ein rudimentäres Konsolenprogramm, das C#-Controller-Code entgegennahm und eine Rohfassung der OpenAPI-Spezifikation als YAML ausgab.

Doch die erste Version war alles andere als praxistauglich:

• - Keine HTTP-Schnittstelle, sondern lokale Ausführung nur auf dem Entwicklerrechner
• - Roh-YAML als Terminalausgabe ohne Formatierung oder Validierung
• - Keine Fehlerbehandlung für ungültige Eingaben oder KI-Ausgaben
• - Keine Möglichkeit, das Tool mit anderen zu teilen oder in bestehende Workflows zu integrieren

Trotz aller Einschränkungen bewies die Phase 1, dass die Kernidee funktioniert: KI kann OpenAPI-Spezifikationen aus reinem C#-Code generieren.

Phase 2: Vom Terminal zum Docker-Container

Die größte Hürde lag darin, das Tool für andere nutzbar zu machen. Die Lösung war die Umwandlung der Konsolenanwendung in eine REST-API mit zwei Endpunkten:

// ASP.NET Core Minimal API-Endpunkte
app.MapPost("/generate-openapi", async (string code) => await GenerateOpenApi(code));
app.MapGet("/health", () => "Service is running");

Diese API akzeptiert den C#-Code als JSON-Payload und liefert die generierte OpenAPI-Spezifikation als YAML zurück. Parallel wurde ein Dockerfile erstellt, das den Dienst in einem Container verpackt. Dies ermöglichte die einfache Verteilung und Ausführung mit einem einzigen Befehl:

docker run -p 8080:80 -e OLLAMA_HOST=host.docker.internal:11434 itod/autodoc

Der entscheidende Vorteil: Die Konfiguration des KI-Modells (in diesem Fall Llama 3.2) erfolgt über eine Umgebungsvariable, sodass der Dienst sowohl lokal als auch in einer Docker-Umgebung laufen kann.

Phase 3: Die browserbasierte Benutzeroberfläche

Die finale Phase brachte die Benutzerfreundlichkeit auf ein neues Level. Statt einer separaten Frontend-Anwendung wurde ein einfaches Dashboard direkt in den Docker-Container integriert und über wwwroot ausgeliefert. Die Playground-Oberfläche besteht aus vier Hauptkomponenten:

• Split-Panel-Layout: Links der Code-Editor, rechts die Echtzeit-Ausgabe
• Roh-YAML-Tab: Die vollständige generierte Spezifikation im lesbaren Format
• Swagger-Vorschau: Eine interaktive Swagger-UI, die direkt aus der YAML generiert wird
• Status-Anzeige: Echtzeit-Feedback über den Generierungsfortschritt

Ein besonderer Komfortfaktor ist die vorbefüllte Beispiel-Controller-Klasse. Ohne jede Einrichtung können Nutzer sofort loslegen und die Funktionsweise von AutoDoc testen.

Ein praktisches Beispiel: Vom C#-Code zur fertigen OpenAPI-Spezifikation

Die Stärke von AutoDoc zeigt sich in der Praxis. Betrachten wir einen einfachen C#-Controller, der Aufgaben verwaltet:

[ApiController] [Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll() => Ok(new[] { "Task 1", "Task 2" });
}

Dieser Code enthält keine OpenAPI-spezifischen Attribute, keine XML-Kommentare und keine manuellen Annotationen. Dennoch generiert AutoDoc daraus eine vollständige OpenAPI-Spezifikation, die folgende Elemente automatisch ableitet:

• operationId: Eindeutige Bezeichner wie GetAllTodos oder CreateTodo
• tags: Gruppierung nach Controller-Namen wie TodoController
• summary: Lesbare Beschreibungen für jeden Endpunkt
• responses: Automatische Erkennung von Statuscodes wie 200, 201, 400, 404 und 500
• components/schemas: Generierung einer globalen Fehlerstruktur, die in der gesamten Spezifikation referenziert wird

Die generierte OpenAPI-Spezifikation enthält beispielsweise:

paths:
  /api/Todo:
    get:
      operationId: GetAllTodos
      tags:
        - TodoController
      summary: Gibt alle Aufgaben zurück
      responses:
        '200':
          description: Erfolgreiche Abfrage
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '500':
          $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

Besonders bemerkenswert ist die automatische Erkennung des Rückgabetyps Ok(new[] { "Task 1", "Task 2" }) als Array von Strings. Die KI versteht die Semantik des Codes und übersetzt sie korrekt in die OpenAPI-Spezifikation.

Die größten Herausforderungen: KI-Ausgaben stabilisieren

Llama 3.2 ist ein kostenloses, lokales KI-Modell, das erstaunlich gut funktioniert – aber nicht fehlerfrei. Die größten Probleme lagen in der Konsistenz der Ausgabe:

• Kleinere Syntaxfehler in der generierten YAML führten zu Parsing-Fehlern in Swagger
• Inkonsistente Formatierung machte die Vorschau unleserlich
• Fehlende Referenzen für generierte Schemata brachen die Validierung

Die Lösung bestand in einem mehrstufigen Validierungsprozess:

• - Die generierte YAML wird zunächst auf syntaktische Korrektheit geprüft
• - Fehlende oder fehlerhafte Elemente werden automatisch korrigiert
• - Die finale Version wird gegen die OpenAPI-Spezifikation validiert

Erst diese Stabilisierung machte AutoDoc zu einem zuverlässigen Werkzeug, das direkt in den Entwicklungsworkflow integriert werden kann.

Ausblick: Dokumentation als Nebeneffekt des Codes

AutoDoc beweist, dass KI-gestützte Dokumentation mehr als nur ein Experiment ist – sie ist ein Game-Changer für die API-Entwicklung. Die größte Stärke des Tools liegt darin, dass Entwickler sich keine Gedanken mehr über Dokumentation machen müssen. Stattdessen wird sie automatisch generiert, immer aktuell und immer konsistent mit dem tatsächlichen Code.

Die nächsten Schritte für AutoDoc könnten die Integration in Build-Pipelines oder die Unterstützung weiterer Programmiersprachen umfassen. Doch unabhängig von den zukünftigen Erweiterungen steht bereits jetzt fest: Dokumentation muss kein manueller Aufwand mehr sein. Mit Tools wie AutoDoc wird sie zum automatischen Nebenprodukt der Codeentwicklung – präzise, aktuell und ohne zusätzliche Belastung für das Team.