Swagger-PHP est toujours la première chose qui vient à l'esprit lorsqu'on pense à générer une spécification Swagger pour un projet PHP. Alors, qu'est-ce que Swagger-PHP ? Comment crée-t-on des spécifications en utilisant Swagger-php ? Dans cet article, nous répondrons à ces questions et vous présenterons les détails.

Qu'est-ce que Swagger-PHP ?

swagger-PHP est un outil pour générer de la documentation d'API en utilisant Swagger (maintenant connu sous le nom de la spécification OpenAPI) en PHP. swagger-php aide les développeurs PHP à créer de la documentation d'API basée sur la spécification Swagger (OpenAPI). Cet outil peut générer des spécifications Swagger (OpenAPI) à partir de code PHP. Il permet aux développeurs de définir des points de terminaison d'API, des requêtes et des réponses dans le code, et de générer automatiquement une spécification Swagger (OpenAPI).

Fonctionnalités de Swagger-PHP

Swagger-PHP est un outil puissant utilisé pour générer des spécifications pour les versions OpenAPI 3.0 et 3.1. Il est également capable d'enregistrer des API en utilisant le code source PHP. L'attribut d'annotation utilisé par Swagger-php peut être soit des blocs de documentation, soit php 8.1, ce qui le rend très flexible et polyvalent.

Que vous travailliez avec des blocs de documentation ou la dernière version de PHP, Swagger-php peut vous aider à rationaliser votre processus de développement d'API et à le rendre plus efficace dans l'ensemble.

Comment installer et configurer dans Swagger-PHP

Pour commencer à utiliser Swagger-PHP, vous devez d'abord l'installer. Swagger-PHP peut être installé en utilisant Composer, un gestionnaire de dépendances pour PHP.

Pour installer Swagger-PHP, exécutez la commande suivante dans votre terminal :

composer require zircote/swagger-php

Une fois installé, vous pouvez commencer à utiliser Swagger-PHP pour générer de la documentation Swagger pour votre API.

Ensuite, vous devez configurer Swagger-PHP en créant une nouvelle instance Swagger et en la configurant avec les informations de votre API. Voici un exemple de la façon de configurer Swagger-PHP :

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="My API",
 *         description="API documentation for My API",
 *         @SWG\Contact(name="My Company"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

Dans cet exemple, nous avons créé une nouvelle instance Swagger et l'avons configurée avec les informations de notre API, telles que le chemin de base, les schémas et les informations de l'API (version, titre, description, contact et licence).

Une fois que vous avez configuré Swagger-PHP, vous pouvez commencer à ajouter des annotations Swagger à votre code d'API pour générer de la documentation Swagger. Nous aborderons cela plus en détail dans la section suivante.

Création de documentation Swagger avec Swagger-PHP

Swagger-PHP est une bibliothèque PHP pour générer des documents Swagger. Dans cette section, nous allons apprendre à créer de la documentation Swagger en utilisant Swagger-PHP.

Étape 1. Définition des informations de l'API

Tout d'abord, nous devons définir les informations de l'API. Cela inclut le titre, la description, la version, etc. de l'API. Voici un exemple :

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ]);

Étape 2. Définition des points de terminaison de l'API

Ensuite, nous devons définir les points de terminaison de l'API. Cela inclut les méthodes HTTP, les chemins, les paramètres et les réponses pour chaque point de terminaison. Voici un exemple :

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ]);

Étape 3. Définition du modèle de données

Enfin, nous devons définir les modèles de données. Cela inclut les attributs et les types de chaque modèle. Voici un exemple :

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'My API',
        'description' => 'This is a sample API documentation.',
        'version' => '1.0.0'
    ])
    ->get('/users', [
        'summary' => 'Get a list of users.',
        'description' => 'Returns a list of users.',
        'responses' => [
            '200' => [
                'description' => 'A list of users.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/User'
                    ]
                ]
            ]
        ]
    ])
    ->post('/users', [
        'summary' => 'Create a new user.',
        'description' => 'Creates a new user.',
        'parameters' => [
            [
                'name' => 'user',
                'in' => 'body',
                'description' => 'The user to create.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'The created user.',
                'schema' => [
                    '$ref' => '#/definitions/User'
                ]
            ]
        ]
    ])
    ->definitions([
        'User' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'name' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

Étape 4. Exportation des documents Swagger

Enfin, nous pouvons afficher la documentation Swagger en utilisant le code suivant :

header('Content-Type: application/json');
echo $swagger->toJson();

Cela affichera un document Swagger au format JSON qui peut être utilisé pour générer de la documentation d'API.

Intégration de Swagger UI avec Swagger-PHP

Pour utiliser pleinement les avantages de la documentation Swagger, il est important d'avoir une interface conviviale pour afficher et interagir avec la documentation. C'est là que Swagger-ui entre en jeu. Swagger-UI est une interface Web qui offre une expérience interactive pour afficher et tester la documentation Swagger.

L'intégration de Swagger-UI avec Swagger-PHP est un processus simple. Tout d'abord, téléchargez la dernière version de Swagger-UI à partir du référentiel GitHub officiel. Ensuite, extrayez le contenu de l'archive téléchargée dans un répertoire sur votre serveur Web.

Ensuite, créez un nouveau fichier PHP qui servira de point d'entrée pour Swagger-UI. Dans ce fichier, incluez les fichiers CSS et JavaScript nécessaires pour Swagger-UI, ainsi que la bibliothèque JavaScript Swagger-ui elle-même. Vous devrez également inclure le fichier JSON généré par Swagger-PHP qui contient votre documentation d'API.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // Build a system
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

Dans l'exemple ci-dessus, remplacez les espaces réservés path/to par les chemins réels vers les fichiers CSS et JavaScript de Swagger-UI, ainsi que le fichier JSON généré par Swagger-PHP.

Une fois que vous avez créé ce fichier, vous pouvez accéder à Swagger-UI en accédant à son URL dans votre navigateur Web. Vous devriez voir une interface Swagger-ui entièrement fonctionnelle qui affiche votre documentation d'API et vous permet d'interagir avec elle.

En conclusion, l'intégration de Swagger-UI avec Swagger-PHP est un processus simple qui améliore considérablement la convivialité de votre documentation d'API. En suivant les étapes décrites ci-dessus, vous pouvez facilement créer une interface conviviale pour votre documentation d'API qui permettra aux développeurs de comprendre et d'utiliser plus facilement votre API.

Partager les spécifications de l'API

Après avoir généré la spécification Swagger, je la partage souvent avec les membres de mon équipe. Dans ces cas, nous partageons souvent au format Swagger JSON ou OpenAPI yaml, mais cela semble un peu dépassé.

Ici, Apidog est l'outil de gestion d'API parfait qui génère instantanément des spécifications d'API très lisibles basées sur les données Swagger JSON ou YAML. Vous pouvez également partager facilement cette spécification d'API avec la fonction de partage d'API.

Apidog fournit également diverses fonctions en tant qu'outil de gestion du cycle de vie des API.

Conception d'API et génération de spécifications : Apidog est l'outil de conception d'API le plus simple à utiliser, vous permettant de concevoir intuitivement des API sans code et de générer confortablement des spécifications OpenAPI et Swagger.

Gestion des API et tests unitaires : Apidog facilite les tests unitaires, car vous pouvez gérer efficacement votre API, envoyer des requêtes d'API et valider les réponses.

Automatisation des tests d'API : Apidog prend également en charge les tests automatisés et est prêt pour CI/CD. En utilisant cette fonction pour définir le nombre de threads, etc., vous pouvez facilement implémenter des tests de charge d'API et l'automatisation des tests d'API.

Conclusion

En conclusion, Swagger-PHP est un outil puissant pour générer de la documentation Swagger pour les API basées sur PHP. Il permet aux développeurs de documenter facilement leurs API et de les rendre accessibles aux autres développeurs. De plus, l'intégration de Swagger-UI avec Swagger-php fournit une interface conviviale pour explorer et tester les API.

Voici quelques ressources pour en savoir plus sur Swagger-PHP :

Documentation officielle : https://zircote.github.io/swagger-php/
Référentiel GitHub : https://github.com/zircote/swagger-php
Swagger-ui : https://swagger.io/tools/swagger-ui/