Utiliser ThinkPHP6 pour générer automatiquement des documents API

À mesure que les API sont de plus en plus utilisées, la génération automatique de documents API est devenue un outil indispensable. Cet article explique comment utiliser le framework ThinkPHP6 pour générer automatiquement des documents API.

1. Introduction au framework ThinkPHP6

ThinkPHP6 est un framework open source efficace, simple, pratique et flexible développé en utilisant le langage PHP. Il adopte un modèle de développement orienté objet, prend en charge l'architecture MVC (Model-View-Controller) et dispose de fonctions puissantes telles que des moteurs de routage, de mise en cache, de vérification et de modèles.

2. Installez Swagger UI

Swagger est un outil de génération automatique de documents API. Il peut générer automatiquement des documents API et fournir une interface Web pour démontrer les résultats d'exécution de l'API. Lorsque vous utilisez ThinkPHP6 pour générer automatiquement des documents API, nous devons d'abord installer Swagger.

Nous pouvons installer Swagger via l'outil Composer. Entrez dans la ligne de commande :

composer require zircote/swagger-php

Une fois l'installation terminée, créez un fichier de configuration Swagger dans le répertoire racine du projet et nommez-le swagger.php :

<?php
return [
    'swagger' => [
        'api' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'paths' => [
            APP_PATH . '/',
        ],
        'exclude' => [
        ],
        'swagger-ui' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'securityDefinitions' => [
        ],
    ],
];

3. Définissez les commentaires du document API

Afin d'autoriser Swagger pour identifier et générer automatiquement la documentation des API, nous devons ajouter les commentaires correspondants dans le code. ThinkPHP6 fournit un format de commentaire personnalisé pour définir la documentation de l'API.

Définissez les commentaires du document API dans le contrôleur :

<?php
declare(strict_types=1);

namespace appcontroller;

class Example
{
    /**
     * @OAGet(
     *      path="/example/index",
     *      operationId="exampleIndex",
     *      tags={"Example"},
     *      summary="示例接口",
     *      description="这是一个示例接口",
     *      @OAResponse(
     *          response=200,
     *          description="操作成功",
     *      ),
     *      @OAResponse(
     *          response=401,
     *          description="未授权",
     *      ),
     *      security={
     *          {"Bearer": {}}
     *      }
     * )
     */
    public function index()
    {
        //接口代码
    }
}

Dans le code ci-dessus, la balise de commentaire commençant par @OA est analysée au format canonique de Swagger. Parmi eux, @OAGet définit la méthode de requête de l'API comme la méthode Get ; path définit le chemin de l'API ; operationId définit l'identifiant de l'opération ; les balises définissent la balise à laquelle appartient le résumé de l'API ; ; description définit la description détaillée de l'API ; @OAResponse définit le résultat de la réponse et le code d'état de l'API ;

4. Générer la documentation de l'API

Après avoir défini les annotations de la documentation de l'API, nous pouvons utiliser Swagger pour générer la documentation de l'API. Entrez la commande suivante sur la ligne de commande :

php think swagger:export --output public/swagger.json

Cette commande enregistrera le document API dans le fichier swagger.json dans le répertoire public.

5. Accédez à la documentation de l'API

Utilisez l'interface utilisateur Swagger pour afficher la documentation de l'API. Nous pouvons déployer le projet Swagger UI sur un serveur Web ou l'exécuter localement.

Lors d'une exécution locale, nous pouvons utiliser la commande suivante pour démarrer rapidement un service d'interface utilisateur Swagger :

docker run --rm -p 8080:8080 -e SWAGGER_JSON=/data/swagger.json -v /path/to/swagger.json:/data/swagger.json swaggerapi/swagger-ui

Où, /path/to/swagger.json est le chemin absolu du fichier swagger.json.

Visitez http://localhost:8080 dans votre navigateur pour consulter la documentation de l'API.

6. Résumé

Cet article explique comment utiliser le framework ThinkPHP6 et Swagger pour générer automatiquement des documents API. La génération automatique de documents API peut améliorer l'efficacité du développement et réduire les coûts de maintenance. Grâce à l'introduction de cet article, je pense que les lecteurs peuvent déjà utiliser habilement le framework ThinkPHP6 et Swagger pour réaliser la génération automatique de documents API.

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!