New Semantics

English

Deutsch

English

Deutsch

Theme

OpenAPI-Build ​

Dieses Verzeichnis enthält das Build-Script, das docs/public/openapi.json aus den #[OA\*]-Attributen der PHP-Handler generiert.

Voraussetzungen ​

  • PHP 8.2+ im PATH (der CMS-Server hat PHP 8.4/8.5 installiert).
  • composer install unter _core/libs/swagger-php/ (einmalig durchgelaufen).

Lokaler Build ​

Der Build muss auf einer Umgebung mit PHP-Runtime laufen — typischerweise auf dem CMS-Server selbst. Ohne PHP im PATH bricht das Script mit einer klaren Fehlermeldung ab.

bash
cd docs
npm run build:openapi

Das ruft intern scripts/build-openapi.sh auf, welches wiederum _core/libs/swagger-php/bin/openapi mit den korrekten Scan- und Exclude- Pfaden aufruft.

Ergebnis ​

  • docs/public/openapi.json (OpenAPI 3.0, JSON-Format)
  • Wird von der Scalar-Komponente in docs/api-reference/index.md geladen.

Scan-Pfade ​

Das Script scannt:

  1. _core/system/api/ — zentrale Meta-Klasse + Schemas
  2. _public/extensions/core/backend/ — alle Plugin-API-Handler

Ausgeschlossen werden Vendor-SDKs (PayPal, Stripe, PDF-Parser, SimpleSAML), kompilierte Smarty-Templates (templates_c/), Media-Uploads (z_uploads/) und node_modules/. Details siehe build-openapi.sh.

CI / Server-Deployment ​

Wenn die Docs auf einem dedizierten Host gehostet werden (nicht am Server), empfiehlt sich:

  1. npm run build:openapi auf dem CMS-Server ausführen.
  2. Das generierte docs/public/openapi.json ins Docs-Repo committen oder per CI-Job synchronisieren.
  3. Docs-Host führt nur noch npm run build aus (statische Seite + Scalar- Viewer, keine PHP-Runtime nötig).

Troubleshooting ​

  • "php: command not found" → PHP ist nicht im PATH. Lokales Development-Env (macOS ohne Homebrew-PHP) kann den Build nicht laufen lassen, das ist ok — Build ist Server-Aufgabe.
  • "Cannot redeclare class" → Irgendein Vendor-SDK wurde nicht per --exclude ausgeblendet. Unsere Marker-Klassen sind im Namespace Newmeta\OpenApi\Schemas, also eher unwahrscheinlich; aber Exclude-Liste in build-openapi.sh prüfen.
  • Leere openapi.json → Scan hat keine Attribute gefunden. Prüfen, ob use OpenApi\Attributes as OA; in den Handler-Files korrekt gesetzt ist.