api_platform:
    title: 'TQ-Slator — Management API'
    version: '1.0.0'
    description: |
        API de gestion des traductions.

        Deux APIs cohabitent et ne doivent pas être confondues :

        - **Management API** (`/api/v1`, cette documentation) — création de clés,
          saisie de traductions, administration. Authentification par session
          (back-office) ou par clé API scopée (CLI, intégrations).
        - **Delivery API** (`/delivery/v1`) — lecture des bundles publiés par les
          applications en production. Immuable, cachable, clé API en lecture seule.

        Le stockage des valeurs est **toujours** en ICU MessageFormat canonique.
        Les formats propres aux plateformes (i18next…) sont produits à la
        publication, jamais stockés.

    formats:
        # JSON-LD par défaut : il apporte hydra:totalItems et hydra:view, dont la
        # grille virtualisée du back-office a besoin pour dimensionner sa barre de
        # défilement. Le JSON nu renvoie un tableau sans métadonnée de pagination.
        jsonld: ['application/ld+json']
        # Disponible via Accept: application/json — c'est ce que consomment le CLI
        # et les intégrations simples, qui n'ont que faire d'Hydra.
        json: ['application/json']

    docs_formats:
        jsonopenapi: ['application/vnd.openapi+json']
        html: ['text/html']

    defaults:
        # Combiné au préfixe /api du routing d'API Platform, les ressources
        # sortent sous /api/v1/... — versionné dès le premier jour, parce
        # qu'ajouter une version à une API déjà consommée est un chantier.
        route_prefix: /v1

        # `false` est imposé par le choix d'authentification par session
        # (cookie SameSite + CSRF) plutôt que par jeton porteur : Symfony refuse
        # de lire la session sur une requête déclarée sans état.
        #
        # Conséquence : les réponses de la Management API ne sont pas cachables
        # publiquement. Ce n'est pas un problème — c'est la Delivery API qui
        # porte la charge de lecture, et elle est stateless de bout en bout.
        stateless: false
        cache_headers:
            vary: ['Content-Type', 'Authorization', 'Origin']
        pagination_client_items_per_page: true
        pagination_maximum_items_per_page: 500
        pagination_items_per_page: 50

    swagger:
        # Déclare le schéma d'authentification pour que le bouton « Authorize »
        # de la page de documentation soit fonctionnel. Sans lui, les endpoints
        # sont documentés mais impossibles à essayer depuis un navigateur, ce qui
        # vide la doc interactive de son intérêt.
        api_keys:
            cleApi:
                name: Authorization
                type: header

    exception_to_status:
        App\Translation\Format\Exception\MessageParseException: 422
        App\Translation\Format\Exception\UnsupportedMessageFeatureException: 422