Désormais, nous savons écrire des endpoint manuellement. Cependant :
Dans ce TD, nous allons mettre en place un outil nommé Swagger, qui permet d'explorer la documentation d'une API (au format OpenAPI), et aussi de tester en direct ses méthodes.
Si vous le souhaitez, vous pouvez repartir du dépôt suivant, qui intègre le code des TDs précédents:
Nous allons installer NelmioApiDocBundle, une bibliothèque qui nous permettra de générer semi-automatiquement la documentation d'API :
symfony composer require nelmio/api-doc-bundle
symfony composer require zircote/swagger-php
Éditez ensuite config/routes.yaml
et ajoutez-y :
app.swagger_ui:
path: /api/doc
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
Maintenant, rendez-vous sur http://localhost:8000/api/doc et observez le résultat :
Les routes et méthodes de l'API sont automatiquement documentées par la bibliothèque. Vous pouvez à présent tester les méthodes de l'API directement depuis l'interface ("Try it out").
Afin de documenter les endpoints, vous pouvez ajouter des
attributs
OA\Get
(par exemple) à vos actions.
use OpenApi\Attributes as OA;
// À ajouter au niveau du contrôleur
#[OA\Get(
summary: "Search a message using an address",
tags: ["Message"],
)]
Il est également possible d'ajouter des attributs OA\Parameter
au niveau des paramètres des actions.
use OpenApi\Attributes as OA;
// À ajouter au niveau du contrôleur
#[OA\Parameter(
description: "Address to search",
in: "query",
required: true,
example: "17 rue des orangers, Paris"
)]
#[MapQueryParameter()] string $address,
Documentez les paramètres address
, radius
et posted_after
.
Vous pourrez vous aider des
références
Voici à quoi devrait ressembler le résultat :
Observez les schémas en bas de la page. Ils sont générés automatiquement à partir des types de sérialisation utilisés.
À l'aide de l'attribut suivant, vous pouvez ajouter des informations sur les propriétés des objets,
essayez par exemple de documenter la propriété text
du type Message
:
#[OA\Property(description: "Message text", example: "This is a message contents!")]
private ?string $text = null;
À l'aide d'un alias de type, créez un schema MessageBasic
qui représentera un type Message
vu sous le groupe de sérialisation message_basic
.
Vous pouvez consulter les schémas en bas de la documentation
Créez un schéma personnalisé, qui
décrira le schema MessageSearchResult
, la réponse à une recherche de messages.
À l'aide d'un attribut similaire à celui ci-dessous, documentez le type de retour de la méthode de recherche:
#[OA\Response(
response: 200,
description: "Search result",
content: new OA\JsonContent(
ref: "#/components/schemas/MessageSearchResult"
)
)]
Le résultat devrait ressembler à ceci :
À l'aide des exemples précédents, assurez vous que l'ensemble des endpoints existants soient correctement documentés.