Swagger

Il existe un outils Swagger qui permet de generer la doc des API que l'on créé.

Cela peut fonctionner dans PHP avec la librairie swagger-php qui va permettre a travers des annotations PHP de générer la documentation.

Vidéo pour Installer Swagger-UI

Par defaut l'UI pointe sur un fichier https://petstore.swagger.io/v2/swagger.json.

Il faut faire cette petite modification du code de la page HTML pour le faire pointer vers le fichier public/swagger/swagger.json

On modifie le code de la page HTML public/swagger/index.html

On remplace url: “https://petstore.swagger.io/v2/swagger.json”, par url: “swagger.json”,

 window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "swagger.json",       <<<<< ICI ON MODIFIE L'URL
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],

Qui permettra de generer la description de l'API au format OpenAPI via la commande commande?

Pour installer : composer require zircote/swagger-php

D:\webprojects\test-api-project>composer require zircote/swagger-php
Using version ^3.0 for zircote/swagger-php
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Restricting packages listed in "symfony/symfony" to "4.3.*"
Package operations: 1 install, 0 updates, 0 removals
  - Installing zircote/swagger-php (3.0.2): Downloading (100%)
Writing lock file
Generating autoload files
ocramius/package-versions: Generating version class...
ocramius/package-versions: ...done generating version class
Executing script cache:clear [OK]
Executing script assets:install public [OK]

dans votre projet creer un dossier swagger

Dans ce dossier créer un fichier swagger.php qui contiendra les infos de bases de vos APIs sous forme d'Annotations

swagger.php

<?php
 
use OpenApi\Annotations as OA;
 
/**
 * @OA\Info(title="APIs l'informaTIC",version="0.1")
 * @OA\Server(
 *      url="http://api.linformatic.fr",
 *      description="APIs de l'informaTIC"
 * )
 */

Executer la commande vendor\bin\openapi.bat –format json –output public\swagger\swagger.json swagger\swagger.php src pour generer un fichier JSON (swagger.json) de description des vos API dans le dossier public

D:\webprojects\test-api-project>vendor\bin\openapi.bat --format json --output public\swagger\swagger.json swagger\swagger.php src 
Required @OA\PathItem() not found

Le fichier généré est celui là :

swagger.json

{
    "openapi": "3.0.0",
    "info": {
        "title": "APIs TechTIC",
        "version": "0.1"
    },
    "servers": [
        {
            "url": "http://api.techtic.pro",
            "description": "APIs de TechTIC"
        }
    ]
}

On se rends sur l'URL http://127.0.0.1:8000/swagger/ et on devrait obtenir cela :

Voir la vidéo de GrafikArt sur Swagger et OpenAPI pour plus di'nformations