Einen API-Endpunkt anlegen

6 Schritte·ca. 25 Min.·Einsteiger·Stand: September 2026

Sie bauen einen Endpunkt vom Controller bis zur React-Komponente. Die Typen im Frontend entstehen aus der OpenAPI-Beschreibung, die der Server selbst ausliefert.

Was Sie bauen

Den Endpunkt GET /api/bundle/acme/status, der in der API-Referenz steht, und eine Komponente, die seine Antwort über useAcmeStatusGetQuery() anzeigt.

Voraussetzungen

  • Zuerst durcharbeiten: Ein Bundle anlegen
  • Die Entwicklungsumgebung läuft, die App ist unter http://app.vendority.local erreichbar
  • Node.js und npm für das Frontend des Bundles
Schritt 1 von 6

Schritt 1 von 6

Die Antwort beschreiben

Legen Sie zuerst fest, was der Endpunkt zurückgibt. Eine kleine Klasse mit OpenAPI-Attributen beschreibt die Antwort für den Server und für das Frontend.

src/Status/Schema/AcmeStatus.php Neue Datei
<?php
declare(strict_types=1);

namespace Vendority\Bundle\Acme\Status\Schema;

use OpenApi\Attributes\Property;
use OpenApi\Attributes\Schema;

#[Schema(
    schema: 'AcmeStatus',
    title: 'AcmeStatus',
    description: 'Whether the Acme bundle is ready.',
    required: ['message', 'checkedAt'],
    type: 'object',
)]
final readonly class AcmeStatus
{
    public function __construct(
        #[Property(description: 'Greeting from the Acme bundle', type: 'string', example: 'Acme ist bereit.')]
        private string $message,
        #[Property(description: 'When the server answered', type: 'string', format: 'date-time')]
        private string $checkedAt,
    ) {
    }

    public function getMessage(): string
    {
        return $this->message;
    }

    public function getCheckedAt(): string
    {
        return $this->checkedAt;
    }
}
  1. 1

    #[Schema] nimmt die Klasse in die OpenAPI-Beschreibung auf. Aus dem Namen AcmeStatus wird später ein TypeScript-Typ.

  2. 2

    Felder unter required sind im generierten Typ Pflichtfelder. Fehlt ein Feld dort, macht der Generator daraus message?: string.

  3. 3

    #[Property] beschreibt jedes Feld mit Typ und Beispiel. Mit format: 'date-time' weist die Referenz checkedAt als Zeitstempel aus.

  4. 4

    Der Serializer liest die Werte über die Getter. Ein Feld ohne Getter fehlt in der Antwort, auch wenn es im Konstruktor steht.

Schritt 2 von 6

Den Controller schreiben

Ein Controller in Vendority erledigt genau eine Aktion und erbt vom Basis-Controller des Core.

src/Status/Controller/StatusController.php Neue Datei
<?php
declare(strict_types=1);

namespace Vendority\Bundle\Acme\Status\Controller;

use DateTimeImmutable;
use DateTimeInterface;
use OpenApi\Attributes\Get;
use OpenApi\Attributes\JsonContent;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted;
use Symfony\Component\Serializer\SerializerInterface;
use Vendority\Bundle\Acme\Status\Schema\AcmeStatus;
use Vendority\Bundle\Core\Controller\AbstractApiController;
use Vendority\Bundle\Core\OpenApi\Attribute\Response\DefaultResponses;
use Vendority\Bundle\Core\OpenApi\Attribute\Response\SuccessResponse;
use Vendority\Bundle\Core\Util\Constant\HttpResponseCodes;

final class StatusController extends AbstractApiController
{
    private const string BUNDLE_PATH = '/bundle/acme';
    private const string ROUTE = '/status';

    public function __construct(SerializerInterface $serializer)
    {
        parent::__construct($serializer);
    }

    #[Route(self::ROUTE, name: 'vendority_acme_status_get', methods: ['GET'])]
    #[IsGranted('ROLE_USER')]
    #[Get(
        path: self::PREFIX . self::BUNDLE_PATH . self::ROUTE,
        operationId: 'acme_status_get',
        summary: 'acme_status_get_summary',
        tags: ['Bundle - Acme']
    )]
    #[SuccessResponse(
        description: 'acme_status_get_success_response',
        content: new JsonContent(ref: AcmeStatus::class, type: 'object')
    )]
    #[DefaultResponses([HttpResponseCodes::UNAUTHORIZED])]
    public function __invoke(): JsonResponse
    {
        return $this->jsonResponse(new AcmeStatus(
            message: 'Acme ist bereit.',
            checkedAt: (new DateTimeImmutable())->format(DateTimeInterface::ATOM),
        ));
    }
}
  1. 1

    Der Konstruktor reicht den SerializerInterface mit parent::__construct() an AbstractApiController weiter. Ohne diesen Aufruf schlägt jsonResponse() fehl.

  2. 2

    #[Route] enthält nur den Teil nach dem Präfix des Bundles. /api/bundle/acme setzt die Routing-Datei aus dem nächsten Schritt davor.

  3. 3

    #[IsGranted('ROLE_USER')] lässt jede angemeldete Person zu. Im Tutorial „Eine Berechtigung anlegen“ ersetzen Sie das durch eine eigene Berechtigung.

  4. 4

    #[Get] beschreibt denselben Endpunkt für OpenAPI. self::PREFIX ist der Platzhalter {prefix}, den Vendority in der Referenz durch /api ersetzt.

  5. 5

    Aus der operationId entsteht im Frontend der Name des Hooks. Sie muss eindeutig sein; beginnen Sie sie mit dem Namen Ihres Bundles.

  6. 6

    #[SuccessResponse] und #[DefaultResponses] kommen aus dem Core und stehen an der Methode. DefaultResponses trägt 400, 405, 415 und 422 selbst ein, 401 geben Sie mit.

  7. 7

    summary und description enthalten Schlüssel. Die Texte dazu tragen Sie in Schritt 4 ein.

  8. 8

    jsonResponse() gibt das Objekt so aus, wie der Serializer es erzeugt, ohne zusätzliche Hülle.

Schritt 3 von 6

Controller und Route registrieren

Der Core findet Klassen nicht von selbst. Tragen Sie den Ordner der Controller als Services und als Routen ein.

config/services.yaml Geändert
services:
    _defaults:
        autowire: true
        autoconfigure: true
    Vendority\Bundle\Acme\Status\Controller\:
        resource: '../src/Status/Controller'
        tags: [ 'controller.service_arguments' ]

+3 Zeilen neu · grau: bestehender Code zur Orientierung

config/routes/attributes.yaml Neue Datei
vendority_acme_api:
    resource: "../../src/Status/Controller"
    type: attribute
    prefix: '/api/bundle/acme'
    host: "%vendority_core.domain%"
Terminal Befehl
docker compose exec -T php php bin/console cache:clear
docker compose exec -T php php bin/console debug:router | grep acme
  1. 1

    Der Eintrag in services.yaml macht jede Klasse im Ordner src/Status/Controller zu einem Service. Über autowire bekommt der Konstruktor den Serializer.

  2. 2

    Dateien unter config/routes/ lädt der Vendority-Kernel für jedes Bundle, dessen Namespace mit Vendority beginnt. In der Host-Anwendung tragen Sie dafür nichts ein.

  3. 3

    prefix setzt /api/bundle/acme vor jede Route aus dem Ordner. host bindet die Routen an die Domain Ihrer Installation, wie bei den mitgelieferten Bundles.

  4. 4

    debug:router zeigt, ob Symfony die Route kennt und unter welchem Pfad.

  5. 5

    Rufen Sie danach http://app.vendority.local/api/bundle/acme/status im Browser auf, während Sie in Vendority angemeldet sind. Ohne Anmeldung antwortet der Server mit 401.

Schritt 4 von 6

In die API-Referenz aufnehmen

Vendority erzeugt die API-Referenz aus den Attributen im Code. Sagen Sie dem Core, wo er in Ihrem Bundle suchen soll, und liefern Sie die Texte mit.

config/packages/vendority_core.yaml Neue Datei
vendority_core:
    open_api_scan_paths:
        - '%kernel.project_dir%/vendor/vendority/acme-bundle/src'
translations/vendority_api_docs.en.yaml Neue Datei
acme_status_get_summary: "Status of the Acme bundle"
acme_status_get_success_response: "A greeting and the time the server answered."
Terminal Befehl
docker compose exec -T php php bin/console cache:clear
  1. 1

    Der Core liest die Attribute aus allen Ordnern unter open_api_scan_paths. Ihr Eintrag kommt zu denen des Core und der anderen Bundles hinzu.

  2. 2

    Geben Sie den Pfad unter vendor/ an. Composer legt das Bundle dort ab: bei der Entwicklung als Symlink, bei einer Installation aus dem Paketspeicher als Verzeichnis. Einen Pfad unter dev/ gibt es auf installierten Systemen nicht.

  3. 3

    Existiert ein eingetragener Pfad nicht, bricht die gesamte Referenz mit einer InvalidPathException ab, auch für alle anderen Endpunkte.

  4. 4

    Werte in summary, description und title, die wie ein Schlüssel aussehen, sucht Vendority in der Übersetzungsdomain vendority_api_docs. Fehlt der Eintrag, zeigt Vendority den Schlüssel in Worten an, hier „Acme status get“.

  5. 5

    Die API-Referenz ist auf Englisch. Die mitgelieferten Bundles bringen deshalb nur vendority_api_docs.en.yaml mit.

  6. 6

    Öffnen Sie http://app.vendority.local/api/docs. Die Seite gibt es nur in der Umgebung dev.

Schritt 5 von 6

Den Client generieren

Das Frontend fragt den Endpunkt über RTK Query ab. Den Code dafür erzeugt ein Generator aus der Beschreibung, die der Server liefert.

assets/build/api/config/openapi-config.cjs Neue Datei
const pathMatcher = (pattern) => {
    return (name, definition) => {
        return pattern.test(definition.path);
    };
}

const config = {
    schemaFile: './docs.jsonopenapi.json',
    apiFile: '@vendority/core/api',
    apiImport: 'api',
    exportName: 'api',
    hooks: true,
    tag: true,
    endpointOverrides: [],
    outputFiles: {
        '../acme-api-slice.gen.ts': {
            filterEndpoints: pathMatcher(/bundle\/acme\//i)
        }
    }
}

module.exports = config
assets/package.json Geändert
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "build-api-client": "npx @rtk-query/codegen-openapi ./build/api/config/openapi-config.cjs",
    "verify:css": "node node_modules/@vendority/core/js/src/sdk/vite/verify-bundle-css.mjs"
  },

+1 Zeile neu · grau: bestehender Code zur Orientierung

Terminal Befehl
cd dev/vendority/acme-bundle/assets
npm install --save-dev @rtk-query/codegen-openapi
curl -s http://app.vendority.local/api/docs/json -o build/api/config/docs.jsonopenapi.json
npm run build-api-client
  1. 1

    npm install --save-dev nimmt den Generator @rtk-query/codegen-openapi in die devDependencies auf. Das neue Skript build-api-client ruft ihn mit der Konfiguration auf.

  2. 2

    Der Generator liest eine gespeicherte Kopie der Beschreibung, die Datei docs.jsonopenapi.json. Nach jeder Änderung an den Attributen laden Sie die Datei neu herunter und generieren erneut.

  3. 3

    filterEndpoints übernimmt nur Pfade, die bundle/acme/ enthalten. Die übrigen Pfade in der Datei gehören dem Core und anderen Bundles.

  4. 4

    Mit apiFile: '@vendority/core/api' landen die Endpunkte in der API-Instanz des Core, die sich die App mit allen Bundles teilt.

  5. 5

    Aus der operationId acme_status_get wird der Hook useAcmeStatusGetQuery. Aus einem GET entsteht eine Query, aus den anderen Methoden eine Mutation.

Schritt 6 von 6

Den Hook in einer Komponente verwenden

Eine React-Komponente holt jetzt die Daten und zeigt sie an.

assets/js/src/modules/status/components/acme-status-card.tsx Neue Datei
import { useAcmeStatusGetQuery } from '@vendority/acme/api/acme-api-slice.gen'

export const AcmeStatusCard = (): React.JSX.Element | null => {
  const { data, isLoading } = useAcmeStatusGetQuery()

  if (isLoading || data === undefined) {
    return null
  }

  return (
    <div className="acme:rounded-xl acme:border acme:px-4 acme:py-3 acme:text-sm">
      {data.message}
    </div>
  )
}
  1. 1

    @vendority/acme/api zeigt auf assets/build/api. Für Vite richtet createVendorityPluginConfig() den Alias ein, für TypeScript der Eintrag "@vendority/acme/api/*" in der tsconfig.json aus „Ein Bundle anlegen“.

  2. 2

    Solange die Antwort fehlt, ist data leer, und die Komponente zeigt nichts an.

  3. 3

    data.message hat den Typ string. Einen falschen Feldnamen meldet tsc bei npm run build.

  4. 4

    Die Klassen tragen das Präfix acme: wie alle Tailwind-Klassen Ihres Bundles.

  5. 5

    Bauen Sie das Frontend mit npm run build, oder lassen Sie während der Arbeit npm run dev laufen.

Geschafft.

Sie haben „Einen API-Endpunkt anlegen“ von Anfang bis Ende durchgearbeitet.

Blättern auch mit ← und →