winzik/docs/ide/fr/api-platform.md

104 lines
8.6 KiB
Markdown

# API Platform
La fenêtre **API Platform** (barre d'outils du bas ; Search Everywhere : *API Platform : …*) apparaît dans un projet dont le `composer.json`
exige `api-platform/core` (ou un autre paquet `api-platform/*`). Elle lit l'API dans les sources, sans rien exécuter : les attributs
`#[ApiResource]` des classes des dossiers PSR-4 (entités et DTO, propriétés promues du constructeur comprises), leurs opérations,
`#[Groups]`, `#[ApiProperty]` et `#[ApiFilter]`. Cinq onglets ; la fenêtre peut prendre tout l'écran (bouton ⤢, Échap la rend). Dans la
fenêtre Doctrine, l'éditeur d'entité et le menu du diagramme ont une entrée **API Platform…** qui ouvre une classe ici.
**API Platform n'est pas encore installé ?** Cocher *API Platform resource (#[ApiResource])* dans la boîte **Nouvelle entité** affiche un
bandeau (*API Platform n'est pas installé dans ce projet*) avec un bouton **Installer API Platform** ; *Nouveau… > Installer API Platform…* aussi.
La commande est montrée (`composer require api`, le pack Flex de Symfony, pour Symfony 6.4+ avec Flex ; `api-platform/symfony` sans Flex ;
`api-platform/core:^3.2` / `^2.7` pour un Symfony plus ancien, lu dans `composer.lock`), lancée par le lanceur de la fenêtre Composer avec sa
sortie en direct, et la fenêtre API Platform apparaît sans redémarrer l'IDE. Refusé : l'attribut est quand même écrit, avec un avertissement
(la classe est indéfinie tant que le paquet n'est pas installé). Toute autre classe indéfinie (`Undefined class 'X\Y'`) a la correction rapide
**Installer le paquet manquant…** (candidats : une table intégrée des espaces de noms courants, puis Packagist).
![Les options d'une ressource et ses opérations](../images/api-platform-resource.png)
Chaque changement est **calculé ici et montré en diff d'abord** ; rien n'est écrit avant *Appliquer*. Seuls les arguments touchés changent :
l'attribut est modifié argument par argument (positions de `php-parser`), tout le reste garde ses octets exacts, le style de la liste (une
ligne ou un argument par ligne) est suivi, et les lignes `use` sont ajoutées. Une valeur que le code tient pour une expression
(`security: self::RULE`, `'groups' => [Book::READ]`) est affichée telle quelle et jamais réécrite.
![Le diff avant l'écriture](../images/api-platform-diff.png)
## Ressources
La liste de gauche contient les entités et DTO du projet (badge `API` si la classe a `#[ApiResource]` ; filtre par classe ou nom court).
Pour la classe choisie :
- **#[ApiResource] oui / non** : *L'exposer avec #[ApiResource]* ajoute l'attribut (et son `use`), *Retirer #[ApiResource]* l'enlève. Une
classe à plusieurs `#[ApiResource]` (une **sous-ressource** a son propre `uriTemplate` + `uriVariables`) montre une pastille par
attribut ; **Sous-ressource** en ajoute un.
- **Général** : nom court, modèle d'URI, **variables d'URI** (`new Link(fromClass:, fromProperty:, toProperty:)`).
- **Sérialisation et validation** : groupes de *normalisation*, de *dénormalisation* et de *validation* (pastilles ; les autres clés du
contexte, `enable_max_depth`… restent).
- **Sécurité** : `security`, `securityPostDenormalize`, `securityMessage`.
- **Pagination** : activée (défaut / oui / non), éléments par page, contrôle du client, maximum par page.
- **Formats et ordre** : `jsonld`, `json`, `jsonapi`, `hal`, `xml`, `csv`, `html` ; l'ordre par défaut (`['title' => 'ASC']`).
- **State** : `provider`, `processor`, `input`, `output` (une classe, ou `false`).
- **Opérations** : `Get`, `GetCollection`, `Post`, `Put`, `Patch`, `Delete`, chacune avec sa route (méthode et chemin) et ses options
propres (nom, `uriTemplate`, `controller`, sécurité, groupes, pagination, provider / processor / input / output) : ajout, suppression,
changement de type. Quand le code n'en liste aucune, les opérations par défaut d'API Platform sont montrées (Get, GetCollection, Post,
Patch, Delete ; Put aussi avant API Platform 4) ; *Les rendre explicites pour les modifier* écrit la liste.
## Propriétés
![La grille des propriétés](../images/api-platform-groups.png)
Une grille, une ligne par propriété (une clé marque l'identifiant ; le type Doctrine ou la relation est indiqué). **Colonnes de groupes** :
les groupes de sérialisation des contextes de la ressource et des propriétés ; chaque case est l'attribut `#[Groups([...])]` (créé,
modifié ou retiré). En en-tête, **R** et **W** disent si le groupe est un groupe de *lecture* (`normalizationContext` de la ressource) et / ou
d'*écriture* (`denormalizationContext`) ; les basculer modifie la ressource dans le même diff, et **+ Groupe** ajoute une colonne. Puis :
**Lisible**, **Modifiable**, **Identifiant**, **Description**, **Exemple** (`#[ApiProperty]`, retiré s'il ne lui reste aucun argument) et
**Filtres** : `SearchFilter` (stratégie `exact`, `partial`, `start`, `end`, `word_start`), `OrderFilter`, `RangeFilter`, `DateFilter`,
`BooleanFilter`, `ExistsFilter`, `NumericFilter` en attributs `#[ApiFilter(...)]` (un filtre déjà là garde ses autres arguments). Les
filtres déclarés sur la classe sont listés sous la grille.
## State
Les classes qui implémentent `ProviderInterface` / `ProcessorInterface`, avec leurs usages. **Nouveau provider…** / **Nouveau processor…**
écrivent une classe depuis un modèle (`src/State/`), éventuellement en **décorant ceux de Doctrine** (providers de collection / d'élément,
processor de persistance, injectés avec `#[Autowire]`), et la branchent à la ressource dans le même diff (`processor: BookProcessor::class`).
**Brancher…** connecte une classe existante.
## Routes
Toutes les routes, déduites du code (méthode, chemin avec le préfixe de `config/routes/api_platform.yaml`, ressource, opération,
sécurité, nom) ; un clic ouvre la ressource. **Comparer avec debug:router** lance `debug:router` par le lanceur de la fenêtre Console et
marque chaque route ✓ / ✗, et liste les routes d'API de la console que le code n'explique pas. **Export OpenAPI** montre
`api:openapi:export`.
## Requêtes
![L'état de chaque fichier de requête](../images/api-platform-requests.png)
![La collection générée dans le client HTTP](../images/api-platform-http-client.png)
**Générer pour toutes les ressources** (ou pour une) fabrique, pour chaque ressource, une collection du [client HTTP](http-client.md)
`http-requests/<Ressource>/` :
- un fichier `.http` par opération (`list`, `get`, `create`, `replace`, `update`, `delete`, `<personnalisée>` ; les sous-ressources dans un
dossier `sub-…`) : URL sous `{{baseUrl}}`, la méthode, `Accept` et `Content-Type` (`application/ld+json`, ou le premier des `formats` ;
`application/merge-patch+json` pour `PATCH`), un **corps d'exemple** construit avec les propriétés que l'opération écrit (groupes de
dénormalisation, `#[ApiProperty(writable: false)]` exclu, la classe `input` s'il y en a une) avec des valeurs d'exemple selon le type
(`#[ApiProperty(example:)]`, le premier cas d'un enum, une IRI pour une relation), les **filtres en paramètres de requête commentés**
(`# ?title=…`, `# ?order[title]=asc`, `# ?pages[gte]=1`, `# ?page=2`), un test de statut, et un script qui garde le nouvel id (`{{bookId}}`
utilisé par les autres requêtes) ;
- une nouvelle collection reçoit l'environnement (`baseUrl`, les ids, le login) et, avec `lexik/jwt-authentication-bundle`, une requête de
**login JWT** (lue dans `security.yaml`) que l'authentification de la collection utilise.
**La régénération** suit la classe, avec une règle : une requête que quelqu'un a modifiée n'est jamais écrasée. Le `.apiplatform.json` de la
collection garde l'empreinte de ce que l'outil a écrit. Un fichier encore identique est réécrit (ou supprimé si l'opération a disparu) ; un
fichier différent, ou que l'outil n'a jamais écrit, reste tel quel et la nouvelle version est écrite à côté sous `nom.theirs.http` (seulement
s'il y a du nouveau). La fenêtre montre l'état de chaque fichier (nouveau, sera rafraîchi, à jour, le vôtre conservé, supprimé) et le diff
avant l'écriture.
## Tests
`ide/tests/ApiPlatformTest.php` : les attributs lus sous plusieurs formes, le texte exact de chaque changement
(`tests/fixtures/api-platform-expected/`), la grille des propriétés, les classes State, les requêtes et les règles de régénération.
`games/ide/tools/api-platform-check.sh <une copie d'un projet Symfony avec api-platform/core>` est le contrôle réel : une entité faite par le
backend de la fenêtre Doctrine, `#[ApiResource]` modifié, `debug:router`, et les requêtes générées exécutées par le client HTTP contre
`php -S`. `games/ide/tools/ui-api-platform-check.sh` prend les captures de cette page.