API Platform OpenAPI Dokumentation anpassen

1. Warum die generierte OpenAPI Dokumentation Nacharbeit braucht

API Platform generiert aus den Ressourcen Attributen automatisch eine vollständige OpenAPI Spezifikation, inklusive Schemas, Statuscodes und Query Parametern. Für interne Teams reicht dieser Automatismus oft schon aus, weil sie den Code kennen und Rückfragen kurz sind. Sobald aber externe Partner oder eine öffentliche API angeboten wird, zeigt sich schnell, dass die generierte OpenAPI Dokumentation technische Feldnamen zeigt, aber keinen Kontext liefert, warum ein Feld existiert oder welche Werte in der Praxis sinnvoll sind.

API Platform erlaubt es, jede Operation gezielt zu dokumentieren, ohne die generierte Basis komplett zu verwerfen. Über das openapiContext Argument am Operation Attribut lassen sich Summary, Beschreibung, Beispiele und sogar veraltete Markierungen direkt in der PHP Klasse pflegen, sodass Code und OpenAPI Dokumentation nie auseinanderlaufen können, weil beide aus derselben Quelle stammen.

Der zweite Baustein ist der OpenApiFactory Decorator, mit dem sich globale Aspekte wie Info Block, Server URLs und Sicherheitsschemas zentral pflegen lassen, statt sie in jeder einzelnen Ressource zu wiederholen. Beide Mechanismen zusammen erlauben eine OpenAPI Dokumentation, die sowohl präzise als auch wartbar bleibt.

2. Summaries und Beschreibungen direkt am Attribut

Der einfachste Einstieg in eine bessere OpenAPI Dokumentation ist das openapi Argument direkt am Operation Attribut. Es akzeptiert ein Operation Objekt aus dem OpenAPI Namespace mit summary und description, die in Swagger UI prominent über dem Endpunkt erscheinen. Statt einer generischen Beschreibung wie Retrieves the collection of Order resources steht dort dann ein Satz, der tatsächlich erklärt, wofür der Endpunkt im Fachkontext genutzt wird.

Diese Beschreibungen sollten nie nur den technischen Vorgang wiederholen, sondern den Geschäftskontext liefern: Welche Nutzergruppe ruft den Endpunkt typischerweise auf, welche Nebenwirkungen hat ein Aufruf, und welche Fehlerfälle sind zu erwarten. Diese Informationen fehlen in einer rein aus Reflection generierten OpenAPI Dokumentation komplett und müssen von Hand ergänzt werden.

<?php

declare(strict_types=1);

namespace App\ApiResource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Model\Operation as OpenApiOperation;

/**
 * Documents the checkout operation with a meaningful summary
 * that goes beyond the auto generated default text.
 */
#[ApiResource(
    operations: [
        new Post(
            uriTemplate: '/orders/{id}/checkout',
            openapi: new OpenApiOperation(
                summary: 'Finalizes an order and triggers payment capture',
                description: 'Transitions the order into the "confirmed" state, '
                    . 'reserves stock and requests payment capture from the '
                    . 'configured payment provider. Idempotent per order id.',
            ),
        ),
    ],
)]
final class CheckoutOrder
{
    public string $id;
}

3. Eigene Beispiele für Requests und Responses

Konkrete Beispiele sind der Teil der OpenAPI Dokumentation mit dem größten praktischen Nutzen, weil Entwickler eher ein funktionierendes Beispiel kopieren, als ein Schema zeilenweise zu lesen. API Platform erlaubt über openapiContext das Hinterlegen eigener examples Blöcke pro Operation, die in Swagger UI als Try It Out Vorlage erscheinen.

Besonders wichtig sind realistische Beispiele bei Feldern mit mehrdeutigem Format, etwa Geldbeträgen als Integer in kleinster Einheit oder Datumsangaben mit Zeitzonen Suffix. Ein einziges korrektes Beispiel verhindert hier mehr Supportanfragen als ein ganzer Absatz Fließtext, weil Entwickler das Format direkt am funktionierenden Wert erkennen, statt eine Beschreibung interpretieren zu müssen.

<?php

declare(strict_types=1);

namespace App\ApiResource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;

/**
 * Adds a realistic request example showing the minor unit
 * amount format expected by the payment field.
 */
#[ApiResource(
    operations: [
        new Post(
            openapiContext: [
                'requestBody' => [
                    'content' => [
                        'application/json' => [
                            'example' => [
                                'amountMinorUnits' => 1999,
                                'currency' => 'EUR',
                                'reference' => 'ORDER-2026-000482',
                            ],
                        ],
                    ],
                ],
            ],
        ),
    ],
)]
final class Payment
{
    public int $amountMinorUnits;
    public string $currency;
}

4. Der OpenApiFactory Decorator für globale Anpassungen

Manche Anpassungen betreffen nicht eine einzelne Operation, sondern das gesamte Dokument: Kontaktinformationen, Lizenzangaben, mehrere Server URLs für Staging und Produktion, oder das Entfernen technischer interner Endpunkte aus der öffentlichen OpenAPI Dokumentation. Dafür dekoriert man OpenApiFactoryInterface und modifiziert das fertig gebaute OpenApi Objekt, bevor es ausgeliefert wird.

Dieser Decorator ist auch der richtige Ort, um Endpunkte, die zwar existieren müssen, aber nicht für externe Konsumenten gedacht sind, gezielt aus der öffentlichen Dokumentation zu entfernen, ohne sie technisch zu deaktivieren. So bleibt die OpenAPI Dokumentation für Partner übersichtlich, während interne Werkzeuge weiterhin auf denselben Endpunkten arbeiten können.

<?php

declare(strict_types=1);

namespace App\OpenApi;

use ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface;
use ApiPlatform\OpenApi\Model\Contact;
use ApiPlatform\OpenApi\Model\Info;
use ApiPlatform\OpenApi\OpenApi;

/**
 * Decorates the generated OpenApi document with contact info
 * and removes internal only paths from the public spec.
 */
final readonly class InternalPathsOpenApiFactory implements OpenApiFactoryInterface
{
    public function __construct(
        private OpenApiFactoryInterface $decorated,
    ) {
    }

    public function __invoke(array $context = []): OpenApi
    {
        $openApi = $this->decorated->__invoke($context);

        $info = new Info(
            title: $openApi->getInfo()->getTitle(),
            version: $openApi->getInfo()->getVersion(),
            description: 'Public API for order management and checkout',
            contact: new Contact(name: 'API Support', email: 'api@mironsoft.de'),
        );

        $paths = $openApi->getPaths();
        $paths->removePath('/internal/health-check');

        return $openApi->withInfo($info)->withPaths($paths);
    }
}

5. Sicherheitsschemas korrekt dokumentieren

Ein häufig übersehener Teil der OpenAPI Dokumentation sind die Sicherheitsschemas. Wenn eine API mit Bearer Tokens oder OAuth2 gesichert ist, muss das components.securitySchemes Objekt korrekt gepflegt sein, sonst kann Swagger UI keinen Autorisierungsdialog anzeigen und externe Entwickler wissen nicht, wie sie sich authentifizieren sollen. Über den OpenApiFactory Decorator lässt sich ein SecurityScheme Objekt mit Typ http, Schema bearer und Format JWT global registrieren.

Zusätzlich sollte jede Operation, die Authentifizierung erfordert, im security Feld explizit darauf verweisen, statt sich auf eine implizite globale Regel zu verlassen. Das macht die OpenAPI Dokumentation an jedem einzelnen Endpunkt eindeutig lesbar, ohne dass ein Entwickler an anderer Stelle im Dokument nachschauen muss, ob und wie ein Endpunkt geschützt ist.

6. Tags und Gruppierung für große APIs

Bei APIs mit mehr als einem Dutzend Ressourcen wird die Standard Swagger UI Ansicht schnell unübersichtlich. API Platform unterstützt das tags Array pro Operation, mit dem sich verwandte Endpunkte in Swagger UI zu aufklappbaren Gruppen zusammenfassen lassen, etwa Bestellungen, Zahlungen und Versand getrennt statt einer einzigen langen Liste.

Über den OpenApiFactory Decorator lassen sich zusätzlich Tag Beschreibungen und eine feste Reihenfolge definieren, sodass die wichtigsten Ressourcen für neue Entwickler oben in der Dokumentation erscheinen, statt in alphabetischer Reihenfolge zufällig verteilt zu sein.

7. Eigene Operationen ohne CRUD Semantik dokumentieren

Nicht jeder Endpunkt folgt dem klassischen CRUD Muster. Eine Aktion wie Bestellung stornieren oder Bericht exportieren lässt sich zwar technisch als POST Operation abbilden, braucht aber eine OpenAPI Dokumentation, die klar macht, dass hier keine neue Ressource erzeugt wird, sondern ein Zustandswechsel oder ein Seiteneffekt ausgelöst wird. Das openapi Argument mit eigenem summary ist hier Pflicht, weil die automatische Ableitung aus dem Ressourcennamen bei solchen Aktionen meist irreführend ist.

Zusätzlich lohnt es sich, bei solchen Aktionsendpunkten explizit die möglichen Fehlerantworten im responses Block der OpenAPI Dokumentation zu ergänzen, etwa einen 409 Konflikt Statuscode, wenn eine Bestellung bereits storniert wurde. Ohne diese Ergänzung geht ein Client Entwickler oft erst nach dem ersten Fehlschlag in Produktion davon aus, dass dieser Fall überhaupt möglich ist.

8. Dokumentation über mehrere API Versionen hinweg pflegen

Sobald eine API mehrere aktive Versionen gleichzeitig unterstützt, muss auch die OpenAPI Dokumentation pro Version separat ausgeliefert werden, damit ein Client nicht versehentlich Felder einer neueren Version in der alten Dokumentation sieht. Der OpenApiFactory Decorator kann anhand des im Context übergebenen Versionsparameters unterschiedliche Info Objekte und sogar unterschiedliche Pfad Mengen zurückgeben.

Ein deprecated Flag direkt an der betroffenen Operation ist zusätzlich Pflicht, sobald ein Endpunkt in einer neueren Version ersetzt wurde. Swagger UI zeigt diese Markierung visuell deutlich an und verweist im besten Fall über die Beschreibung gleich auf den Nachfolger Endpunkt, was Migrationsaufwand für Konsumenten deutlich reduziert.

9. Dokumentationsansätze im Vergleich

Die folgende Tabelle zeigt, welcher Mechanismus für welche Art von Anpassung an der OpenAPI Dokumentation der richtige ist.

In der Praxis kombinieren gut dokumentierte API Platform Projekte beide Mechanismen: Operation Attribute für den fachlichen Kontext direkt am Code, und einen einzigen OpenApiFactory Decorator für alles, was das gesamte Dokument betrifft. Diese Aufteilung hält die OpenAPI Dokumentation konsistent, ohne dass Änderungen an mehreren Stellen gleichzeitig gepflegt werden müssen.

10. Zusammenfassung

Die automatisch generierte OpenAPI Dokumentation von API Platform ist ein solider Ausgangspunkt, ersetzt aber nicht die manuelle Pflege von Geschäftskontext, konkreten Beispielen und korrekt dokumentierten Sicherheitsschemas. Über das openapi Argument am Operation Attribut lassen sich Summary, Beschreibung und Beispiele direkt am Code pflegen, während der OpenApiFactory Decorator globale Aspekte wie Info Block, Sicherheitsschemas und interne Pfade zentral steuert.

Wer beide Mechanismen konsequent nutzt, bekommt eine OpenAPI Dokumentation, die nicht nur technisch korrekt ist, sondern externen Entwicklern tatsächlich hilft, eine API ohne ständige Rückfragen zu integrieren. Gerade bei öffentlichen APIs mit fremden Partnerteams ist diese Investition in die Dokumentation direkt messbar an der Zahl der Supportanfragen.

11. FAQ: OpenAPI Dokumentation in API Platform