# ? Documentation Swagger - API 

Ce dossier contient les spécifications OpenAPI (Yaml). Cette documentation vous permettra de comprendre
comment ajouter une nouvelle API au swagger, d'intéragir avec les différentes API déjà présentes,
et de savoir comment les utiliser.

## ? Lien URL vers le Swagger

```
https://default.prod.stream-up.local/fo-swagger.php
```

## Structure des fichiers

```
docs/
??? swagger/
?   ??? swagger_main.yml                         # Point d'entrée principal (metadata globale)
?   ??? openapi/
?       ??? openapi-comptes-utilisateurs.yaml
?       ??? openapi-evenements-live.yaml
?       ??? openapi-sondages-questions.yaml
?       ??? openapi-licences.yaml
?       ??? openapi-medias-videos.yaml
?       ??? openapi-alertes-notifications.yaml
?       ??? openapi-listes-indices.yaml
?       ??? openapi-utilisateurs-groupes.yaml
?       ??? openapi-breakout-middleware.yaml
?       ??? openapi-cache-config-eposter-conteneurs.yaml
```
Chaque fichier correspond à un groupe fonctionnel exposé dans l'interface Swagger UI via
le sélecteur de définition.

## Ajouter un endpoint
### 1. Identifier le bon fichier

Chaque fichier regroupe les endpoints d'un domaine métier. Ouvre le fichier YAML correspondant dans `docs/swagger/openapi/`.

### 2. Ajouter le path
Dans la section `paths` du fichier YAML, ajoute le nouvel endpoint en respectant la structure suivante :

```yaml
paths:
    /api-new-endpoint:
        post:
        summary: "Description courte de l'endpoint"
        description: "Description détaillée de ce que fait l'endpoint."
        tags:
            - "Tag de regroupement"
        requestBody:
            required: true
            content:
            application/json:
                schema:
                type: object
                properties:
                    param1:
                    type: string
                    description: "Description du paramètre 1"
                    param2:
                    type: integer
                    description: "Description du paramètre 2"
        responses:
            '200':
            description: "Réponse réussie"
            content:
                application/json:
                schema:
                    type: object
                    properties:
                    status:
                        type: string
                        example: "success"
                    data:
                        type: object
                        description: "Données retournées par l'endpoint"
            '400':
            description: "Requête invalide"
            content:
                application/json:
                schema:
                    type: object
                    properties:
                    status:
                        type: string
                        example: "error"
                    message:
                        type: string
                        example: "Description de l'erreur"
```

### 3. Déclarer un schéma 
Si l'endpoint retourne un object non encore défini, ajoute-le dans la section `components/schemas` du même fichier YAML :

```yaml
components:
  schemas:
    MonObjet:
      type: object
      properties:
        id:
          type: integer
          example: 42
        nom:
          type: string
          example: "exemple"
```

### 4. Enregistrer un nouveau fichier (si nouveau groupe fonctionnel)

Si tu crées un fichier YAML pour un groupe fonctionnel inexistant : 

- Nomme-le 'openapi-{]nom-du-groupe}.yaml' et place-le dans `docs/swagger/openapi/`.
- Ajoute le nom-du-groupe dans la liste $allowed de 'api-swagger.php' pour qu'il soit reconnu par l'interface Swagger UI.
- Ajoute l'entrée correspondante dans le tableau 'urls[]' de 'fo-swagger.php' : 

```javascript
{ url: 'api-swagger.php?file=openapi-{nom-du-groupe}.yaml', name: 'Nom du groupe' },
```

### 5. Lancer le rendu local
- Assurer vous d'avoir bien lancer le projet Streamup en local

url : 
```
https://default.prod.stream-up.local/fo-swagger.php
```

### 6. Paramètre d'URL disponibles

| Paramètre | Valeur                         | Effet |
|-----------|--------------------------------|-------|
| `file` | nom du groupe (ex: `licences`) | Ouvre directement la définition correspondante |
| `selector` | `1`                            | Affiche le sélecteur de définition |
| `selector` | `0`                            | Sélecteur masqué |
| _(absent)_ | ?                              | Sélecteur masqué, définition par défaut |

**Exemples :**
##### Ouvrir directement la spec Breakout Middleware
```
/fo-swagger.php?file=breakout-middleware
```

##### Ouvrir avec le sélecteur visible
```
/fo-swagger.php?file=licencesselector=1
```

### 7. Vérifier qu'un fichier YAML est bien servi
```
https://default.prod.stream-up.local/api-swagger-yaml.php?file=evenements-live
```
Le navigateur doit retourner le contenu YAML brut avec le header `Content-Type: application/yaml`.