Développement PHP : Comment utiliser Swagger pour maintenir la documentation de l'API-tutoriel php-php.cn

Développement PHP : Comment utiliser Swagger pour maintenir la documentation de l'API

WBOY

Libérer： 2023-06-15 09:38:01

original

1006 Les gens l'ont consulté

Avec le développement rapide d'Internet, l'API Web est devenue le cœur du support des applications ouvertes. L'évolutivité et la réutilisabilité des API en font un outil important pour l'échange de données et la collaboration entre différents systèmes. Cependant, les développeurs sont souvent confrontés à une question courante : comment maintenir la documentation des API et garantir leur fiabilité ?

Swagger est un framework open source qui fournit une solution complète pour la conception, la documentation, les tests et le déploiement d'API. Cet article explique comment utiliser Swagger pour maintenir la documentation des API afin de mieux gérer et maintenir les API existantes.

1. Concepts de base de Swagger

Swagger crée et documente les API via des fichiers de spécification JSON ou YAML qui décrivent l'API. Ce fichier est appelé spécification Swagger.

Les fichiers de spécifications Swagger contiennent les concepts suivants :

Chemin : Un chemin d'API est un identifiant pour une ressource. Par exemple, /users représente tous les utilisateurs et /users/{id} représente un utilisateur.
Method : Une méthode HTTP telle que GET, PUT, POST, DELETE et HEAD.
Paramètres : paramètres de requête (corps de la requête HTTP, chemin d'URL et/ou paramètres de chaîne de requête).
Response : structure de réponse HTTP, code d'état et type de corps de réponse (corps de réponse HTTP).
Modèle : Structure de l'objet de transfert de données (DTO) et de l'objet de réponse.
Tags : regroupez logiquement les ressources de l'API pour une lecture facile.

2. Utilisation de Swagger

Installer l'interface utilisateur de Swagger

Swagger UI est une source ouverte Outil qui nous permet d'afficher les fichiers de spécifications Swagger dans une interface interactive. Son objectif principal est de fournir une documentation claire et interactive et de nous permettre de tester et déboguer l'API.

Utilisez la commande suivante pour installer l'interface utilisateur Swagger :

npm install swagger-ui-dist

Copier après la connexion

Écrire le fichier de spécifications Swagger

Écrire le fichier de spécifications Swagger pour décrire le chemin, les méthodes, les paramètres, les réponses et autres informations de notre API.

Voici un exemple :

swagger: '2.0'
info:
  title: User API Root
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      description: Returns all users
      produces:
        - application/json
      responses:
        200:
          description: A list of user names
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 123
              name:
                type: string
                example: John Doe

Copier après la connexion

Dans cet exemple, nous définissons un chemin API "/users" et une méthode GET qui renvoie une API contenant "id" et "name " comme réponse.

Intégrez l'interface utilisateur Swagger

Intégrez l'interface utilisateur Swagger dans votre application Web pour afficher votre fichier de spécifications Swagger. Ajoutez le code HTML suivant à votre page Web :

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "https://api.example.com/swagger",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
    }
  </script>
</body>
</html>

Copier après la connexion

Dans cet exemple, nous chargeons l'interface utilisateur Swagger dans un fichier HTML et transmettons l'adresse URL du fichier de spécification Swagger au SwaggerUIBundle pour afficher la documentation de l'API. .

Test et débogage des API

Test et débogage des API dans les applications Web à l'aide de l'interface utilisateur Swagger.

Grâce à l'interface utilisateur de Swagger, nous pouvons :

Voir la documentation de l'interface.
Automatisez les tests et vérifiez les résultats de la réponse de l'API.
Déboguer l'API et générer des extraits de code.

Summary

Swagger est un excellent framework qui peut fournir aux développeurs une solution complète pour la conception, la documentation, les tests et le déploiement d'API. Grâce à Swagger, nous pouvons mieux gérer et maintenir les API existantes. C'est également l'une des meilleures méthodes dans le cadre du modèle de développement centralisé.

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!