18. Une documentation

On va mettre en place une documentation dans ce chapitre.

 

Ajoutons une documentation

On va ici faire appel au bundle NelmioApiDocBundle en lançant la commande :

composer require nelmio/api-doc-bundle

Ouvrez le fichier nelmio_api_doc.yaml qui se trouve dans config/routes et modifiez le comme ci-dessous :

# Expose your documentation as JSON swagger compliant
#app.swagger:
#    path: /api/doc.json
#    methods: GET
#    defaults: { _controller: nelmio_api_doc.controller.swagger }

## Requires the Asset component and the Twig bundle
## $ composer require twig asset
app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

Exceptionnellement, pour ne pas avoir à s'authentifier quand on veut accéder à une URL, on va désactiver temporairement l'URI /api dans le fichier security.yaml :

security:
    encoders:
        App\Entity\User:
            algorithm: argon2i

    # https://symfony.com/doc/current/security.html#where-do-users-come-from-user-providers
    providers:
        # used to reload user from session & other features (e.g. switch_user)
        app_user_provider:
            entity:
                class: App\Entity\User
                property: username
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        login:
            pattern:  ^/api/login
            stateless: true
            anonymous: true
            json_login:
                check_path:               /api/login_check
                success_handler:          lexik_jwt_authentication.handler.authentication_success
                failure_handler:          lexik_jwt_authentication.handler.authentication_failure

        api:
            pattern:   ^/api
            stateless: true
            anonymous: true
            guard:
                authenticators:
                    - lexik_jwt_authentication.jwt_token_authenticator

    # Easy way to control access for large sections of your site
    # Note: Only the *first* access control that matches will be used
    access_control:
        # - { path: ^/admin, roles: ROLE_ADMIN }
        # - { path: ^/profile, roles: ROLE_USER }
        - { path: ^/api/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
        # - { path: ^/api,       roles: IS_AUTHENTICATED_FULLY }

Accéder à l'URL http://localhost:8000/api/doc depuis votre navigateur web :


 

 

Aïe, une erreur. Il nous manque le composant asset, ajoutons-le en lançant la commande :

composer require asset

 

Retournez sur votre navigateur web et actualisez votre page web 😉


 

Dites bonjour à votre documentation 😊

Elle vous affiche toutes les routes de votre application avec les méthodes associées.

Profitez-en pour supprimer le fichier ApiController dont on ne se sert plus, ainsi que le dossier templates.

Voici votre documentation à jour :


 

Vous pouvez personnaliser votre documentation en regardant la documentation du bundle.

Rendez-vous au chapitre suivant, où on va s'occuper des liens.