Comment utiliser PHP et Swagger pour la génération de documentation API-tutoriel php-php.cn

Comment utiliser PHP et Swagger pour la génération de documentation API

王林

Libérer： 2023-05-11 17:52:02

original

1786 Les gens l'ont consulté

Avec le développement rapide d'Internet, l'API (Application Programming Interface) est devenue un moyen standard de développement d'applications modernes. L'API fait référence à un ensemble d'interfaces qui permettent aux applications d'échanger des données et des fonctions, permettant ainsi aux applications d'interagir les unes avec les autres de manière pratique et rapide.

Après avoir créé une API, afin de permettre à d'autres développeurs d'utiliser notre API, nous devons rédiger une documentation détaillée pour l'API. Cependant, la rédaction manuelle de la documentation API est une tâche longue et consommatrice d'énergie. L'utilisation d'outils automatisés pour la génération de documentation API est donc très nécessaire et efficace.

Cet article expliquera comment utiliser PHP et Swagger pour la génération de documents API.

1. Qu'est-ce que Swagger ?

Swagger est une spécification permettant de décrire et de définir les API RESTful. Il peut être utilisé pour générer une documentation lisible par l'homme, ainsi qu'un générateur de code pour générer du code côté client et côté serveur. Swagger peut également être utilisé pour les tests et le débogage des API.

2. Installation et configuration de Swagger

Pour utiliser Swagger pour générer des documents API, vous devez d'abord l'installer. Nous pouvons utiliser Composer pour installer Swagger Composer est un gestionnaire de dépendances pour PHP et pouvons télécharger la dernière version de Swagger.

Utilisez la commande suivante pour installer Swagger :

composer require "swagger-api/swagger-ui:^3.50"

Copier après la connexion

Une fois l'installation terminée, nous devons effectuer une configuration pour Swagger. Créez un fichier swagger.php dans le répertoire racine du projet et ajoutez le code suivant :

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use OpenApiAnnotations as OA;

$swagger = OpenApiscan('/path/to/your/controllers');

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

Copier après la connexion

Dans le code ci-dessus, /path/to/your/controllers doit être remplacé par votre propre chemin de contrôleur. De plus, nous devons également ajouter quelques configurations au fichier composer.json :

    "config": {
        "platform": {
            "php": "7.4"
        }
    },
    "autoload": {
        "classmap": [
            "app/",
            "database/",
            "routes/",
            "tests/"
        ]
    },
    "require": {
        "php": "^7.4",
        "laravel/framework": "^8.40",
        "tymon/jwt-auth": "^1.0",
        "doctrine/dbal": "^2.13",
        "swagger-api/swagger-ui": "^3.50"
    },
    "require-dev": {
        "facade/ignition": "^2.5",
        "fzaninotto/faker": "^1.9.1",
        "mockery/mockery": "^1.4.2",
        "nunomaduro/collision": "^6.0",
        "phpunit/phpunit": "^9.3.3"
    },

Copier après la connexion

3. Utilisez Swagger pour générer des documents API

Après avoir installé et configuré Swagger, nous pouvons commencer à l'utiliser pour générer des documents API. Nous pouvons utiliser la commande suivante pour générer la documentation de l'API :

php swagger.php > swagger.json

Copier après la connexion

Dans la commande ci-dessus, swagger.php est le fichier de configuration Swagger qui vient d'être créé et swagger.json est le fichier de documentation de l'API que nous avons généré.

4. Utilisez l'interface utilisateur Swagger pour afficher les documents API

Après avoir généré le document API, nous espérons l'afficher afin que d'autres puissent le voir. Vous pouvez utiliser l'interface utilisateur Swagger pour afficher la documentation de l'API. Swagger UI est une bibliothèque JavaScript utilisée pour afficher les informations de l'API RESTful et son implémentation décrite par Swagger.

Nous pouvons ajouter le contenu suivant au fichier index.php dans le répertoire public :

require_once(__DIR__ . '/../vendor/autoload.php');

$swagger = file_get_contents(__DIR__ . '/../swagger.json');
$swaggerData = json_decode($swagger, true);
?>
  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.min.css" >
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }
      *, *:before, *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
  <div id="swagger-ui"></div>

  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"> </script>
  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-standalone-preset.js"> </script>
  <script>
      window.onload = function() {
          // Begin Swagger UI call region
          const ui = SwaggerUIBundle({
            url: "<?php echo '/swagger.json'; ?>",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIStandalonePreset
            ],
            plugins: [
              SwaggerUIBundle.plugins.DownloadUrl
            ],
            layout: "StandaloneLayout"
          })
          // End Swagger UI call region
          
          window.ui = ui
      }
  </script>
  </body>

  </html>

Copier après la connexion

Dans le code ci-dessus, nous utilisons la bibliothèque JavaScript de Swagger UI, à travers laquelle le document API généré peut être présenté comme une belle page HTML La forme se dévoile.

Un exemple de page montrant la documentation de l'API est présenté ci-dessous :

Comment utiliser PHP et Swagger pour la génération de documentation API

5. Conclusion

L'utilisation de Swagger peut facilement générer et gérer la documentation de l'API. Cet article explique comment utiliser PHP et Swagger pour générer des documents API. Les étapes incluent l'installation et la configuration de Swagger, l'utilisation de Swagger pour générer des documents API et l'utilisation de l'interface utilisateur Swagger pour afficher les documents API. Je pense que les lecteurs peuvent facilement utiliser Swagger pour générer leurs propres documents API après l'introduction de cet article.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!