Einen API-Endpunkt anlegen
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.localerreichbar - Node.js und npm für das Frontend des Bundles
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
#[Schema]nimmt die Klasse in die OpenAPI-Beschreibung auf. Aus dem NamenAcmeStatuswird später ein TypeScript-Typ. -
2
Felder unter
requiredsind im generierten Typ Pflichtfelder. Fehlt ein Feld dort, macht der Generator darausmessage?: string. -
3
#[Property]beschreibt jedes Feld mit Typ und Beispiel. Mitformat: 'date-time'weist die ReferenzcheckedAtals Zeitstempel aus. -
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
Der Konstruktor reicht den
SerializerInterfacemitparent::__construct()anAbstractApiControllerweiter. Ohne diesen Aufruf schlägtjsonResponse()fehl. -
2
#[Route]enthält nur den Teil nach dem Präfix des Bundles./api/bundle/acmesetzt die Routing-Datei aus dem nächsten Schritt davor. -
3
#[IsGranted('ROLE_USER')]lässt jede angemeldete Person zu. Im Tutorial „Eine Berechtigung anlegen“ ersetzen Sie das durch eine eigene Berechtigung. -
4
#[Get]beschreibt denselben Endpunkt für OpenAPI.self::PREFIXist der Platzhalter{prefix}, den Vendority in der Referenz durch/apiersetzt. -
5
Aus der
operationIdentsteht im Frontend der Name des Hooks. Sie muss eindeutig sein; beginnen Sie sie mit dem Namen Ihres Bundles. -
6
#[SuccessResponse]und#[DefaultResponses]kommen aus dem Core und stehen an der Methode.DefaultResponsesträgt 400, 405, 415 und 422 selbst ein, 401 geben Sie mit. -
7
summaryunddescriptionenthalten Schlüssel. Die Texte dazu tragen Sie in Schritt 4 ein. -
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
Der Eintrag in
services.yamlmacht jede Klasse im Ordnersrc/Status/Controllerzu einem Service. Überautowirebekommt der Konstruktor den Serializer. -
2
Dateien unter
config/routes/lädt der Vendority-Kernel für jedes Bundle, dessen Namespace mitVendoritybeginnt. In der Host-Anwendung tragen Sie dafür nichts ein. -
3
prefixsetzt/api/bundle/acmevor jede Route aus dem Ordner.hostbindet die Routen an die Domain Ihrer Installation, wie bei den mitgelieferten Bundles. -
4
debug:routerzeigt, ob Symfony die Route kennt und unter welchem Pfad. -
5
Rufen Sie danach
http://app.vendority.local/api/bundle/acme/statusim 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
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
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 unterdev/gibt es auf installierten Systemen nicht. -
3
Existiert ein eingetragener Pfad nicht, bricht die gesamte Referenz mit einer
InvalidPathExceptionab, auch für alle anderen Endpunkte. -
4
Werte in
summary,descriptionundtitle, die wie ein Schlüssel aussehen, sucht Vendority in der Übersetzungsdomainvendority_api_docs. Fehlt der Eintrag, zeigt Vendority den Schlüssel in Worten an, hier „Acme status get“. -
5
Die API-Referenz ist auf Englisch. Die mitgelieferten Bundles bringen deshalb nur
vendority_api_docs.en.yamlmit. -
6
Öffnen Sie
http://app.vendority.local/api/docs. Die Seite gibt es nur in der Umgebungdev.
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 = configassets/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
npm install --save-devnimmt den Generator@rtk-query/codegen-openapiin diedevDependenciesauf. Das neue Skriptbuild-api-clientruft ihn mit der Konfiguration auf. -
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
filterEndpointsübernimmt nur Pfade, diebundle/acme/enthalten. Die übrigen Pfade in der Datei gehören dem Core und anderen Bundles. -
4
Mit
apiFile: '@vendority/core/api'landen die Endpunkte in der API-Instanz des Core, die sich die App mit allen Bundles teilt. -
5
Aus der
operationIdacme_status_getwird der HookuseAcmeStatusGetQuery. Aus einemGETentsteht 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
@vendority/acme/apizeigt aufassets/build/api. Für Vite richtetcreateVendorityPluginConfig()den Alias ein, für TypeScript der Eintrag"@vendority/acme/api/*"in dertsconfig.jsonaus „Ein Bundle anlegen“. -
2
Solange die Antwort fehlt, ist
dataleer, und die Komponente zeigt nichts an. -
3
data.messagehat den Typstring. Einen falschen Feldnamen meldettscbeinpm run build. -
4
Die Klassen tragen das Präfix
acme:wie alle Tailwind-Klassen Ihres Bundles. -
5
Bauen Sie das Frontend mit
npm run build, oder lassen Sie während der Arbeitnpm run devlaufen.
Geschafft.
Sie haben „Einen API-Endpunkt anlegen“ von Anfang bis Ende durchgearbeitet.
Blättern auch mit ← und →