TD3: Documentation d'API

Désormais, nous savons écrire des endpoint manuellement. Cependant :

L'API que nous avons écrite n'est pas documentée, il faudrait avoir une spécification que l'on pourrait fournir à d'autres développeurs du projet,
Les aller-retours avec des outils externes type Postman ne sont pas spécialement pratiques en phase de développement.

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:

https://gitlab-ce.iut.u-bordeaux.fr/webservices/geochat-td-3

Mise en place

Installation de NelmioApiDocBundle et SwaggerPHP

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 :

Test interactif

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").

Documenter

Documentation des Endpoints

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"],
)]

Documentation des paramètres

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 :

Documentation des types de retour

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 :

Documentez les endpoints

À l'aide des exemples précédents, assurez vous que l'ensemble des endpoints existants soient correctement documentés.

Log-in