shortName, Beschreibung und OpenAPI-Metadaten

Die Swagger UI aus Kapitel 6 zeigt aktuell RECHT technische Bezeichnungen – shortName und description auf Resource-Ebene machen die generierte Dokumentation LESBARER, ohne den Code selbst zu beeinflussen.

shortName setzen

api/src/Entity/Project.php

#[ApiResource(
    shortName: 'Projekt',
    description: 'Ein Vorhaben im Aufgaben-Manager, das mehrere Tasks bündelt.',
    operations: [
        // ...
    ]
)]

shortName beeinflusst NICHT den API-Pfad (der bleibt /api/projects), sondern NUR die Bezeichnung, die in Swagger UI, der OpenAPI-Spezifikation und den JSON-LD-@type-Feldern erscheint – hier würde "@type": "Projekt" statt "@type": "Project" in den API-Antworten stehen.

Achtung: Für UNSER Projekt bleiben wir bei den englischen Standard-Bezeichnungen (Project, Tag), da GEMISCHTE Deutsch/Englisch-Namen spätestens bei der React-Anbindung (Block 9) nur zu Verwirrung führen würden – dieses Kapitel zeigt die MÖGLICHKEIT, nicht eine Empfehlung für dieses Projekt.

Beschreibung pro Operation kombiniert mit shortName

new Post(description: 'Legt ein neues Projekt an.'),
new Delete(description: 'Löscht ein Projekt UNWIDERRUFLICH inklusive aller Tasks.'),

Operation-Beschreibungen und Resource-description ERGÄNZEN sich in der Swagger UI: die Resource-Beschreibung erscheint OBEN im jeweiligen Abschnitt, die Operation-Beschreibung DANEBEN bei der jeweiligen Zeile.

Eine Operation als deprecated markieren

new Get(
    deprecated: true,
    description: 'Veraltet, bitte /api/projects/{id}/details verwenden.'
),

deprecated: true zeigt in Swagger UI ein DEUTLICHES visuelles Signal (durchgestrichen/grau), OHNE den Endpunkt tatsächlich zu deaktivieren – nützlich für einen SCHRITTWEISEN Übergang zu einem neuen Endpunkt, statt einen bestehenden abrupt zu entfernen.

Tipp: ALLE hier gezeigten Parameter sind reine METADATEN für Dokumentation/Tooling – sie verändern WEDER die Datenbank noch die tatsächliche Zugriffslogik, GENAU wie uriTemplate in Kapitel 13.