recherche

Maison >développement back-end >tutoriel php >Comment utiliser PHP et Swagger pour la génération de documentation API

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

王林
王林original
2023-05-11 16:40:421790parcourir

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"

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;

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"
    },

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

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>

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!

php JavaScript composer restful json html 接口 public Interface ui 自动化
Déclaration：
Le contenu de cet article est volontairement contribué par les internautes et les droits d'auteur appartiennent à l'auteur original. Ce site n'assume aucune responsabilité légale correspondante. Si vous trouvez un contenu suspecté de plagiat ou de contrefaçon, veuillez contacter admin@php.cn
Article précédent：Optimisation des performances en PHP : optimisations au niveau du code et du serveurArticle suivant：Optimisation des performances en PHP : optimisations au niveau du code et du serveur

Articles Liés

Voir plus