Back

API Dokumentation

15 minutes MITTELSTUFE

Entdecken Sie das automatische API Dokumentationssystem von GEMVC. Erfahren Sie, wie die Bereinigung die Dokumentation erstellt, verwenden Sie PHPDoc Direktiven und exportieren Sie mit einem Klick zu Postman.

What You'll Learn

Automatische Dokumentation

Wie GEMVC Dokumente automatisch aus Ihrem Code generiert

PHPDoc Direktiven

Verwenden Sie @http, @description, @example Direktiven

Postman Export

Ein Klick Export zur Postman Collection

Video Coming Soon...

Was ist die GEMVC API Dokumentation?

GEMVC verfügt über einen integrierten automatischen API Dokumentationsgenerator, der schöne, interaktive HTML Dokumentation aus Ihrem Code erstellt! Der interessanteste Teil: **Wenn Sie die Eingabe in der API Schicht bereinigen, generiert GEMVC automatisch die Dokumentation!**

  • Automatische Generierung - Die Dokumentation wird automatisch aus Ihren Validierungsschemata erstellt
  • Immer aktuell - Verwendet Reflection, um Ihren Code zu scannen, sodass die Dokumente nie veraltet sind
  • Schöne UI/UX - Vollständige grafische Oberfläche, die Frontend Entwickler lieben werden
  • Postman Export - Ein Klick Export zur Postman Collection für einfaches Testen
  • Parameter Extraktion - Extrahiert Parameter automatisch aus definePostSchema() und defineGetSchema()

Wichtiger Punkt: In GEMVC ist die **Bereinigung gleich der Dokumentation!** Wenn Sie definePostSchema() oder defineGetSchema() zur Validierung von Eingaben verwenden, extrahiert GEMVC automatisch diese Parameter und erstellt schöne Dokumentationstabellen für Ihre Frontend Entwickler.

1

Wie die automatische Dokumentation funktioniert

Die Magie: Bereinigung = Dokumentation

Der ApiDocGenerator von GEMVC verwendet Reflection, um Ihre API Service Klassen zu scannen und automatisch Folgendes zu extrahieren:

1. Parameter aus Validierungsschemata

Wenn Sie definePostSchema() oder defineGetSchema() verwenden, extrahiert GEMVC automatisch alle Parameter und erstellt Parametertabellen in der Dokumentation.

Terminal 
<?php
public function create(): JsonResponse
{
    // Dieses Schema erstellt automatisch Dokumentation!
    if(!$this->request->definePostSchema([
        'name' => 'string',        // Erforderlicher Parameter
        'email' => 'email',         // Erforderlicher Parameter
        '?phone' => 'string'       // Optionaler Parameter (? Präfix)
    ])) {
        return $this->request->returnResponse();
    }
    // ...
}

Ergebnis: Die Dokumentation zeigt automatisch eine Tabelle "Body Parameter" mit den Feldern name, email und phone, einschließlich der Angabe, welche erforderlich/optional sind!

2. PHPDoc Direktiven

PHPDoc Kommentare mit speziellen Direktiven liefern zusätzliche Informationen:

  • ✓ @http GET/POST/PUT/DELETE - HTTP Methode
  • ✓ @description - Lesbare Beschreibung
  • ✓ @example - Beispiel URL
  • ✓ @hidden - Methode in der Dokumentation ausblenden

3. Mock Antworten

Die statische Methode mockResponse() liefert Beispiel Antworten, die in der Dokumentation angezeigt werden.

2

Zugriff auf Ihre API Dokumentation

Dokumentation anzeigen

GEMVC erstellt automatisch einen Dokumentations Endpunkt. Besuchen Sie einfach:

Dokumentations URL:

http://localhost/api/index/document

Ersetzen Sie localhost durch Ihre Server URL. Für OpenSwoole verwenden Sie localhost:9501.

Was Sie sehen werden:

  • ✓ Schöne, moderne Benutzeroberfläche mit klarem Design
  • ✓ Alle Ihre API Endpunkte sind nach Dienst organisiert
  • ✓ Parametertabellen (automatisch aus Schemata extrahiert)
  • ✓ Beispiel URLs (aus @example Direktiven)
  • ✓ Mock Antworten (aus der mockResponse() Methode)
  • ✓ Ein Klick Schaltfläche "Export to Postman"
  • ✓ Interaktive Elemente (Klicken zum Kopieren von URLs)
3

Verwendung von PHPDoc Direktiven

Dokumentieren Ihrer API Methoden

Fügen Sie PHPDoc Kommentare mit speziellen Direktiven hinzu, um Ihre Dokumentation zu verbessern:

Terminal 
<?php
namespace App\Api;

use App\Controller\ProductController;
use Gemvc\Core\ApiService;
use Gemvc\Http\Request;
use Gemvc\Http\JsonResponse;

class Product extends ApiService
{
    /**
     * Erstellt ein neues Produkt
     *      * @return JsonResponse
     * @http POST
     * @description Erstellt ein neues Produkt in der Datenbank. Nur Admin und Sales Manager können Produkte erstellen.
     * @example /api/Product/create
     */
    public function create(): JsonResponse
    {
        if (!$this->request->auth(['admin', 'salesManager'])) {
            return $this->request->returnResponse();
        }
        
        if(!$this->request->definePostSchema([
            'name' => 'string',
            'price' => 'float',
            '?description' => 'string'
        ])) {
            return $this->request->returnResponse();
        }
        
        return (new ProductController($this->request))->create();
    }

    /**
     * Produkt nach ID lesen
     *      * @return JsonResponse
     * @http GET
     * @description Ruft ein Produkt anhand der ID aus der Datenbank ab
     * @example /api/Product/read/?id=1
     */
    public function read(): JsonResponse
    {
        if (!$this->request->auth()) {
            return $this->request->returnResponse();
        }
        
        if(!$this->request->defineGetSchema(['id' => 'int'])) {
            return $this->request->returnResponse();
        }
        
        $id = $this->request->intValueGet('id');
        if(!$id) {
            return $this->request->returnResponse();
        }
        
        $this->request->post['id'] = $id;
        return (new ProductController($this->request))->read();
    }
}

Verfügbare Direktiven:

  • @http GET/POST/PUT/DELETE
    Gibt die HTTP Methode für den Endpunkt an
  • @description Ihre Beschreibung hier
    Lesbare Beschreibung, die in der Dokumentation angezeigt wird
  • @example /api/Product/create
    Beispiel URL, die zeigt, wie der Endpunkt aufgerufen wird
  • @hidden
    Blendet die Methode in der API Dokumentation aus (nützlich für Hilfsmethoden)
4

Hinzufügen von Mock Antworten

Beispiel Antworten in der Dokumentation

Fügen Sie eine statische Methode mockResponse() hinzu, um Beispiel Antworten bereitzustellen, die in der Dokumentation angezeigt werden:

Terminal 
<?php
class Product extends ApiService
{
    // ... Ihre API Methoden ...

    /**
     * Generiert Mock Antworten für die API Dokumentation
     *      * @param string $method Der API Methodenname
     * @return array<mixed> Beispiel Antwortdaten für die angegebene Methode
     * @hidden
     */
    public static function mockResponse(string $method): array
    {
        return match($method) {
            'create' => [
                'response_code' => 201,
                'message' => 'created',
                'count' => 1,
                'service_message' => 'Produkt erfolgreich erstellt',
                'data' => [
                    'id' => 1,
                    'name' => 'Beispiel Produkt',
                    'price' => 99.99,
                    'description' => 'Produkt Beschreibung'
                ]
            ],
            'read' => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => 1,
                'service_message' => 'Produkt erfolgreich abgerufen',
                'data' => [
                    'id' => 1,
                    'name' => 'Beispiel Produkt',
                    'price' => 99.99,
                    'description' => 'Produkt Beschreibung'
                ]
            ],
            'update' => [
                'response_code' => 209,
                'message' => 'updated',
                'count' => 1,
                'service_message' => 'Produkt erfolgreich aktualisiert',
                'data' => [
                    'id' => 1,
                    'name' => 'Aktualisiertes Produkt',
                    'price' => 149.99
                ]
            ],
            'delete' => [
                'response_code' => 210,
                'message' => 'deleted',
                'count' => 1,
                'service_message' => 'Produkt erfolgreich gelöscht',
                'data' => null
            ],
            default => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => null,
                'service_message' => null,
                'data' => null
            ]
        };
    }
}

Wichtige Punkte:

  • ✓ Die Methode muss static sein und mockResponse() heißen
  • ✓ Verwenden Sie die @hidden Direktive, um sie aus der Dokumentation auszublenden
  • ✓ Gibt ein Array zurück, das dem Methodennamen entspricht
  • ✓ Beispiel Antworten werden in der Dokumentations UI schön angezeigt
  • ✓ Hilft Frontend Entwicklern, die Antwortstruktur zu verstehen
5

Automatische Parameter Extraktion

Wie Schemata Dokumentation erstellen

Die leistungsstärkste Funktion: **GEMVC extrahiert Parameter automatisch aus Ihren Validierungsschemata!** Sie müssen Parameter nicht manuell dokumentieren.

POST Parameter

Terminal 
<?php
public function create(): JsonResponse
{
    // Dies erstellt automatisch Dokumentation!
    if(!$this->request->definePostSchema([
        'name' => 'string',        // Erforderlich
        'price' => 'float',        // Erforderlich
        '?description' => 'string' // Optional (? Präfix)
    ])) {
        return $this->request->returnResponse();
    }
    // ...
}

Ergebnis: Die Dokumentation zeigt automatisch eine Tabelle "Body Parameter" mit name (string, erforderlich), price (float, erforderlich) und description (string, optional).

GET Parameter

Terminal 
<?php
public function read(): JsonResponse
{
    // Dies erstellt automatisch Dokumentation!
    if(!$this->request->defineGetSchema(['id' => 'int'])) {
        return $this->request->returnResponse();
    }
    // ...
}

Ergebnis: Die Dokumentation zeigt automatisch eine Tabelle "GET Parameter" mit id (int, erforderlich).

Abfrage Parameter (Listen Operationen)

Terminal 
<?php
public function list(): JsonResponse
{
    // Suchbare Felder werden automatisch dokumentiert
    $this->request->findable([
        'name' => 'string',
        'price' => 'float'
    ]);
    
    // Sortierbare Felder werden automatisch dokumentiert
    $this->request->sortable([
        'id',
        'name',
        'price'
    ]);
    
    // ...
}

Ergebnis: Die Dokumentation zeigt automatisch "Abfrage Parameter" mit Filter (name, price) und Sortierung (id, name, price) Abschnitten.

💡 Die Magie:

Wenn Sie die Eingabe mit definePostSchema() oder defineGetSchema() bereinigen, validieren Sie nicht nur Daten, sondern **erstellen automatisch Dokumentation!** GEMVC liest Ihre Schemata und generiert schöne Parametertabellen, die Ihre Frontend Entwickler lieben werden.

6

Export nach Postman

Ein Klick Postman Export

GEMVC bietet einen **Ein Klick Export** nach Postman! Klicken Sie einfach in der Dokumentations UI auf die Schaltfläche "Export to Postman", und Sie erhalten eine voll funktionsfähige Postman Collection.

So exportieren Sie:

  1. 1. Besuchen Sie http://localhost/api/index/document
  2. 2. Scrollen Sie zum oberen Rand der Dokumentationsseite
  3. 3. Klicken Sie auf die Schaltfläche **"Export to Postman"**
  4. 4. Laden Sie die Datei api_collection.json herunter
  5. 5. Importieren Sie in Postman: File → Import → Wählen Sie die JSON Datei

Was exportiert wird:

  • ✓ Alle API Endpunkte mit korrekten HTTP Methoden
  • ✓ Anfrage URLs (aus @example Direktiven)
  • ✓ Anfrage Body Schemata (aus definePostSchema())
  • ✓ Abfrage Parameter (aus defineGetSchema())
  • ✓ Beispiel Antworten (aus mockResponse())
  • ✓ Organisiert nach Dienst (Product, User, etc.)

Vorteile für Frontend Entwickler:

  • ✓ **Keine manuelle Einrichtung** - Alles ist vorkonfiguriert
  • ✓ **Fertig zum Testen** - Alle Endpunkte sind sofort einsatzbereit
  • ✓ **Immer aktuell** - Bei API Änderungen einfach erneut exportieren
  • ✓ **Teamzusammenarbeit** - Teilen Sie die Collection mit Ihrem Team
7

Komplettes Beispiel

Vollständig dokumentierte Produkt API

Hier ist ein vollständiges Beispiel, das alle Dokumentationsfunktionen zeigt:

Terminal 
<?php
namespace App\Api;

use App\Controller\ProductController;
use Gemvc\Core\ApiService;
use Gemvc\Http\Request;
use Gemvc\Http\JsonResponse;

class Product extends ApiService
{
    /**
     * Erstellt ein neues Produkt
     *      * @return JsonResponse
     * @http POST
     * @description Erstellt ein neues Produkt in der Datenbank. Nur Admin und Sales Manager können Produkte erstellen.
     * @example /api/Product/create
     */
    public function create(): JsonResponse
    {
        if (!$this->request->auth(['admin', 'salesManager'])) {
            return $this->request->returnResponse();
        }
        
        // Parameter werden automatisch für die Dokumentation extrahiert!
        if(!$this->request->definePostSchema([
            'name' => 'string',
            'price' => 'float',
            '?description' => 'string'
        ])) {
            return $this->request->returnResponse();
        }
        
        return (new ProductController($this->request))->create();
    }

    /**
     * Produkt nach ID lesen
     *      * @return JsonResponse
     * @http GET
     * @description Ruft ein Produkt anhand der ID aus der Datenbank ab
     * @example /api/Product/read/?id=1
     */
    public function read(): JsonResponse
    {
        if (!$this->request->auth()) {
            return $this->request->returnResponse();
        }
        
        // GET Parameter wird automatisch für die Dokumentation extrahiert!
        if(!$this->request->defineGetSchema(['id' => 'int'])) {
            return $this->request->returnResponse();
        }
        
        $id = $this->request->intValueGet('id');
        if(!$id) {
            return $this->request->returnResponse();
        }
        
        $this->request->post['id'] = $id;
        return (new ProductController($this->request))->read();
    }

    /**
     * Alle Produkte auflisten
     *      * @return JsonResponse
     * @http GET
     * @description Ruft eine Liste aller Produkte mit Filterung und Sortierung ab
     * @example /api/Product/list/?sort_by=name&find_like=name=test
     */
    public function list(): JsonResponse
    {
        // Abfrage Parameter werden automatisch für die Dokumentation extrahiert!
        $this->request->findable([
            'name' => 'string',
            'price' => 'float'
        ]);
        
        $this->request->sortable([
            'id',
            'name',
            'price'
        ]);
        
        return (new ProductController($this->request))->list();
    }

    /**
     * Generiert Mock Antworten für die API Dokumentation
     *      * @param string $method Der API Methodenname
     * @return array<mixed> Beispiel Antwortdaten für die angegebene Methode
     * @hidden
     */
    public static function mockResponse(string $method): array
    {
        return match($method) {
            'create' => [
                'response_code' => 201,
                'message' => 'created',
                'count' => 1,
                'service_message' => 'Produkt erfolgreich erstellt',
                'data' => [
                    'id' => 1,
                    'name' => 'Beispiel Produkt',
                    'price' => 99.99,
                    'description' => 'Produkt Beschreibung'
                ]
            ],
            'read' => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => 1,
                'service_message' => 'Produkt erfolgreich abgerufen',
                'data' => [
                    'id' => 1,
                    'name' => 'Beispiel Produkt',
                    'price' => 99.99,
                    'description' => 'Produkt Beschreibung'
                ]
            ],
            'list' => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => 2,
                'service_message' => 'Produkte erfolgreich abgerufen',
                'data' => [
                    [
                        'id' => 1,
                        'name' => 'Produkt 1',
                        'price' => 99.99
                    ],
                    [
                        'id' => 2,
                        'name' => 'Produkt 2',
                        'price' => 149.99
                    ]
                ]
            ],
            default => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => null,
                'service_message' => null,
                'data' => null
            ]
        };
    }
}

Was dadurch in der Dokumentation erstellt wird:

  • ✓ **create()** - Zeigt POST Methode, Beschreibung, Beispiel URL, Body Parameter Tabelle (name, price, description) und Mock Antwort
  • ✓ **read()** - Zeigt GET Methode, Beschreibung, Beispiel URL, GET Parameter Tabelle (id) und Mock Antwort
  • ✓ **list()** - Zeigt GET Methode, Beschreibung, Beispiel URL, Abfrage Parameter (Filter und Sortierung) und Mock Antwort
  • ✓ **mockResponse()** - Aus der Dokumentation ausgeblendet, liefert aber Beispiel Antworten für alle Methoden

Dokumentations Funktionen

Das Dokumentationssystem von GEMVC bietet eine fantastische Erfahrung für Frontend Entwickler:

✨ Automatisch generiert

Die Dokumentation wird automatisch aus Ihrem Code mittels Reflection erstellt. Kein manuelles Schreiben erforderlich!

🔄 Immer aktuell

Da es Ihren Code scannt, ist die Dokumentation immer mit Ihrer API synchronisiert. Keine veralteten Dokumente!

📦 Postman Export

Ein Klick Export zur Postman Collection. Voll funktionsfähig, sofort einsatzbereit!

🎨 Schöne UI/UX

Modernes, sauberes Design mit interaktiven Elementen. Frontend Entwickler werden es lieben!

📋 Parameter Tabellen

Die automatische Parameter Extraktion aus Schemata erstellt schöne, organisierte Tabellen.

🔗 Interaktiv

Klicken Sie, um URLs zu kopieren, Abschnitte zu erweitern/minimieren und einfach durch Ihre API zu navigieren.

Wichtige Hinweise

  • **Bereinigung = Dokumentation:** Wenn Sie definePostSchema() oder defineGetSchema() verwenden, erstellen Sie automatisch Dokumentation. Es ist keine zusätzliche Arbeit erforderlich!
  • **Optionale Parameter:** Verwenden Sie das ? Präfix (z. B. '?description' => 'string'), um Parameter in der Dokumentation als optional zu kennzeichnen.
  • **Fügen Sie immer Direktiven hinzu:** Fügen Sie @http, @description und @example zu allen öffentlichen API Methoden hinzu, um die beste Dokumentation zu erhalten.
  • **Mock Antworten:** Fügen Sie immer eine mockResponse() Methode hinzu, um Beispiel Antworten für Frontend Entwickler bereitzustellen.
  • **Hilfsmethoden ausblenden:** Verwenden Sie die @hidden Direktive für Methoden, die nicht in der Dokumentation erscheinen sollen (wie mockResponse()).

📚 Dokumentation abgeschlossen!

Ausgezeichnet! Sie haben gelernt, wie GEMVC automatisch schöne API Dokumentation generiert. Ihre Frontend Entwickler werden die interaktive Benutzeroberfläche und den Ein Klick Postman Export lieben!

Zurück zum Lernzentrum API Dokumentations Referenz anzeigen