====== 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.
<note>L'exemple ici est donné sous un projet Symfony et sous Windows</note>


===== Installation =====

==== Installer la partie UI ====

[[https://www.youtube.com/watch?t=1125&v=no0y4ISItiw|Vidéo pour Installer Swagger-UI]]

=== Petite modification ===
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",''

<code php>
 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
        ],
</code>

==== Installer la commande swagger-php ====
Qui permettra de generer la description de l'API au format OpenAPI via la commande ''commande?''

Pour installer : ''composer require zircote/swagger-php''

<code>
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]
</code>
===== Configurer le projet =====
dans votre projet creer un dossier ''swagger''
==== Le fichier source swagger.php ====


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

<code php 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"
 * )
 */
</code>

==== Compilation du fichier en json ====


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''


<code>
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
</code>

==== Resultats swagger.json ====
Le fichier généré est celui là :
<code json swagger.json>
{
    "openapi": "3.0.0",
    "info": {
        "title": "APIs TechTIC",
        "version": "0.1"
    },
    "servers": [
        {
            "url": "http://api.techtic.pro",
            "description": "APIs de TechTIC"
        }
    ]
}
</code>


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

{{:prog:api:swagger1.png|}}




===== Ressources =====

Voir la [[https://www.grafikart.fr/tutoriels/swagger-openapi-php-1160|vidéo de GrafikArt sur Swagger et OpenAPI]] pour plus di'nformations