Différences

Ci-dessous, les différences entre deux révisions de la page.

--- prog:theorie:api:swagger [20/10/2019 17:19]
thierry créée
+++ prog:theorie:api:swagger [18/10/2022 11:29] (Version actuelle)
thierry ↷ Page déplacée de prog:api:swagger à prog:theorie:api:swagger
@@ Ligne 4: / Ligne 4: @@
 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