Comment générer de la documentation API en utilisant Swagger en PHP

Avec le développement continu des applications Web, l'API est devenue l'un des standards du développement d'applications Web modernes. Cependant, à mesure que le nombre et la complexité des API augmentent, leur maintenance et leur documentation deviennent de plus en plus complexes. Pour résoudre ce problème, Swagger a vu le jour. Il s'agit d'un outil permettant de générer de la documentation sur les API, permettant aux développeurs de maintenir et de documenter plus facilement les API, tout en fournissant également une documentation visuelle et diverses autres fonctionnalités. Dans cet article, nous verrons comment générer de la documentation API à l'aide de Swagger en PHP.

Tout d'abord, nous devons installer Swagger. Il existe de nombreuses versions et implémentations de Swagger, mais nous utiliserons ici Swagger-php, qui est une bibliothèque PHP open source qui facilite l'intégration de Swagger dans le code PHP. Nous pouvons utiliser Composer pour installer Swagger-php dans notre projet :

composer require zircote/swagger-php

Une fois Swagger-php installé, nous pouvons commencer à écrire la spécification Swagger pour notre API. Une spécification Swagger est un fichier JSON ou YAML qui décrit tous les détails d'une API, y compris les URL des points de terminaison, les paramètres de demande et de réponse, le modèle de données et les codes d'erreur. Dans Swagger-php, nous pouvons utiliser des annotations PHP pour rédiger des spécifications. Regardons un exemple simple :

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */

Dans cet exemple, nous avons utilisé l'annotation @OA pour écrire la spécification Swagger. @OA est un espace de noms de la bibliothèque Swagger-php utilisé pour définir différents types d'éléments Swagger, tels que Info, Get, Response et Parameter. Nous pouvons utiliser l'annotation @OAInfo pour décrire les informations de base de l'API, telles que le titre et la version. Dans l'annotation @OAGet, nous définissons deux points de terminaison : /users et /users/{id}. Nous décrivons les paramètres de demande et les réponses, et spécifions les codes de réponse de réussite et d'erreur. Ceci n'est qu'un très petit exemple, mais vous pouvez écrire des spécifications Swagger plus complexes en utilisant d'autres annotations @OA, et même décrire l'authentification et l'autorisation de l'API.

Une fois que nous avons écrit notre spécification Swagger, nous pouvons utiliser Swagger-php pour la convertir en un document visuel. Pour cela, nous pouvons utiliser Swagger-ui, une bibliothèque HTML, CSS et JavaScript pour restituer les spécifications Swagger. Nous pouvons utiliser le package Swagger-ui-php en PHP pour intégrer Swagger-ui. Nous pouvons installer Swagger-ui-php dans notre projet en utilisant Composer :

composer require swagger-api/swagger-ui

Une fois Swagger-ui-php installé, nous pouvons intégrer Swagger-ui dans notre application PHP. Nous pouvons ajouter la ligne suivante à notre code HTML pour charger Swagger-ui : Dans l'élément DIV de l'ID "swagger-ui". Nous utilisons du code JavaScript pour charger le fichier Swagger JSON à partir du backend et utilisons SwaggerUIBundle pour le convertir en un magnifique document.

Enfin, pour que Swagger-ui charge notre spécification Swagger, nous devons ajouter une route à notre application qui renvoie le fichier Swagger JSON.

<link rel="stylesheet" type="text/css" href="/vendor/swagger-api/swagger-ui/dist/swagger-ui.css">
<div id="swagger-ui"></div>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-bundle.js"></script>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.onload = function() {
    // 使用来自后端的Swagger JSON文件构造请求
    SwaggerUIBundle({
      url: "/api/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset // 用于额外的UI依赖
      ],
      layout: "StandaloneLayout"
    })
  }
</script>

Dans cet exemple, nous utilisons les annotations OpenApi pour écrire la spécification Swagger, qui est différente de l'exemple précédent. Nous avons également ajouté une route pour renvoyer le fichier Swagger JSON. Nous utilisons la fonction PHP OpenApiscan pour analyser notre dossier routes et convertir la définition de l'API en un objet Swagger JSON, qui est ensuite converti en chaîne JSON et renvoyé au client.

Dans cet article, nous avons appris comment générer de la documentation API en PHP en utilisant Swagger-php et Swagger-ui. À mesure que le nombre et la complexité de nos API augmentent, Swagger peut nous aider à les maintenir et à les documenter plus facilement, tout en fournissant une documentation visuelle sur les API et diverses autres fonctionnalités. En utilisant les annotations PHP pour écrire les spécifications Swagger, nous pouvons éviter d'écrire manuellement la documentation et rendre notre code plus clair et plus facile à maintenir.

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!