Mit Laravel und Swagger loslegen

Eine kurze Anleitung, wie wir als Laravel Agentur mit Swagger + Laravel arbeiten.

Eine gute Dokumentation ist das Rückgrat einer jeden Applikation. Die Dokumentation erlaubt allen nachfolgenden Entwicklern, zu verstehen, wie die Applikation im Detail funktioniert – ohne dass man sich dabei die gesamte Implementierung durchlesen müsste. 

Swagger ist ein Framework, das Echtzeit-Autorisierung und Endpoint-Tests erlaubt – und zwar für Entwickler und Tester gleichermaßen.

Das Setup

Am besten fangen wir mit der Minimalversion der Applikation an, damit wir wirklich alle vom selben Startpunkt aus beginnen. 

Composer

Zuerst müssen wir Composer herunterladen, damit wir unsere Laravel-Applikation kreieren und etwaige Abhängigkeiten herunterladen können: https://getcomposer.org/download/

Laravel

Durch die Nutzung von Composer können wir unsere neue Laravel-Applikation erstellen:

composer create-project --prefer-dist laravel/laravel blog

Lokaler Entwickler-Server

An dieser Stelle nehme ich einfach mal an, dass alle Leser dieser Anleitung ein grundlegendes Verständnis für die Bearbeitung von Host-Files haben. Um Zeit zu sparen, kommt unsere Applikation daher direkt auf den localhost. 

cd blog && php artisan serve

CTRL+C, damit wir den Server stoppen können. 

Swagger

Es hat sich gezeigt, dass Swagger-php das verlässlichste und praktischste Paket für Projekte bietet, bei denen eine Dokumentation innerhalb von Laravel erzeugt werden soll.

Die Installation

composer require zircote/swagger-php

Dateien & Skripten

Swagger benötigt diverse Informationen über unsere Applikation, darunter den Hostnamen – in diesem Fall also localhost.

Es ist sehr wichtig, dass wir die Dateien außerhalb der Root unseres Projekts nicht direkt an die Applikation binden, daher müssen wir zuerst einige Befehle ausführen.

Zuerst erzeugen wir einen Entwicklungsordner und Swagger-Skripten.

mkdir development && cd development
touch swagger.sh && chmod +x swagger.sh
touch swagger-constants.php
touch swagger-v1.php

Innerhalb unserer swagger.sh-Datei müssen wir ein Skript hinzufügen, damit wir unsere Dokumentations-Datei erzeugen können:

#!/bin/bash

mkdir ../public/swagger
php ../vendor/bin/swagger --bootstrap ./swagger-constants.php --output ../public/swagger ./swagger-v1.php ../app/Http/Controllers

Dazu brauchen wir innerhalb der swagger-constants.php- Datei Folgendes:

<?php
define("API_HOST", 'localhost:8000');

Abschließend können wir nun diesen Code in unsere swagger-v1.php-Datei geben:

<?php
/**
 * @SWG\Swagger(
 *     schemes={"http"},
 *     host=API_HOST,
 *     basePath="/",
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="Laravel and Swagger",
 *         description="Getting started with Laravel and Swagger",
 *         termsOfService="",
 *         @SWG\Contact(
 *             email="name@example.com"
 *         ),
 *     ),
 * )
 */

Jetzt können wir endlich folgenden Befehl ausführen:

./swagger.sh
# Output
Swagger-PHP 2.0.13
------------------
-----------------------
0 operations documented
-----------------------

Es funktioniert! Leider müssen wir jetzt immer noch einige Dinge vorbereiten, damit wir die Endpoints unserer App erfolgreich testen können.

Endpoint Dokumentation & Validierung

Für dieses Tutorial erzeugen wir am besten einen benutzerdefinierten Controller namens UserController (app/Http/Controllers/Auth/UserController.php).
Hier müssen wir zuerst einen Endpoint erzeugen, bei dem wir auf diese Funktion zugreifen können.

Das RoutingIn routes.php (app/Http/routes.php) fügen wir Folgendes hinzu:

Route::get('/create', 'UserController@create');

Der Controller

Für den UserController brauchen wir den folgenden Code: 

Jetzt können wir überprüfen, ob dieser Endpoint funktioniert, indem wir ihn in unserem Browser testen:

cd .. && php artisan serve

http://localhost:8000/create?firstname=medium&lastname=reader

# medium reader

Das Swagger UI

Bis jetzt haben wir erreicht, dass unsere Swagger-Dokumentation mit dem jeweiligen Output funktioniert. Jetzt müssen wir noch das User Interface hinzufügen, mithilfe dessen wir mit unseren Endpoints interagieren und sie testen können.

Das swagger.sh-Skript erzeugt dazu einen Unterordner innerhalb des öffentlichen Ordners, der eine Datei mit dem Namen swagger.json enthält. Diese Datei enthält die notwendigen Informationen für das UI über die Endpoints und die erforderlichen Daten, damit der Test ausgeführt werden kann.

/app
/public
|__ /swagger

Die Installation

Vielleicht ist schon jemandem aufgefallen, dass wir in unserem swagger.sh-Skript bereits festgelegt haben, in welchem Ordner unser Swagger-Output landen soll.

Das User Interface

Damit wir ein Interface hinzufügen können, gehen wir auf https://github.com/swagger-api/swagger-ui und laden dort den gesamten Ordner runter. Den geben wir dann in den Swagger-Ordner. 

swagger-api/swagger-ui
swagger-ui — Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful…github.com

Das Skript individualisieren

Jetzt, da wir die Dateien für das User Interface vorbereitet haben, müssen wir noch die Dateipfade anpassen, damit Swagger richtig funktioniert.
Zuerst müssen wir unseren index.html für unseren localhost Server updaten. Am besten copy & pasten wir den von hier: 

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
    <link rel="stylesheet" type="text/css" href="/swagger/swagger-ui.css" >
    <link rel="icon" type="image/png" href="/swagger/favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="/swagger/favicon-16x16.png" sizes="16x16" />
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }
      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }
      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
    <div id="swagger-ui"></div>

    <script src="/swagger/swagger-ui-bundle.js"> </script>
    <script src="/swagger/swagger-ui-standalone-preset.js"> </script>
    <script>
    window.onload = function() {
      // Build a system
      const ui = SwaggerUIBundle({
        url: url = window.location.protocol + "//" + window.location.hostname + ":" + window.location.port + "/swagger/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      window.ui = ui
    }
  </script>
  </body>
</html>

Die sogenannten Swagger Annotations

Annotations, also auf Deutsch Anmerkungen, beschreibt das Schreibformat, in dem Swagger-Dokumentationen ausgegeben werden, damit sie in swagger.json generiert und damit testbar gemacht werden können.

Typischerweise sollten sich die Annotationen in unseren Controllern befinden, die direkt die Endpoints bearbeiten und die Validierung durchführen (app/Http/Controllers).

Am besten sehen wir uns zuerst an, was die wichtigsten Annotation-Blocks tun:

SWG\Get() verrät uns, welche Art von HTTP-Methode zum Einsatz kommt, in unserem Fall holen wir uns Daten (GET).
path, die Route unseres Endpoints “/create”

SWG\Parameter() wir haben zwei Parameter, die wir für unsere Route brauchen  — firstname und lastname
query, der Parameter wird durch einen Query String übermittelt

SWG\Response() beschreibt, welche Art von Antwort und Code wir erhalten werden, falls die Daten korrekt oder inkorrekt sind.
Dazu geben wir die folgenden Swagger-Annotations über unsere create()-Funktion und führen ein letztes Mal ./swagger.sh aus.

/**
 * @SWG\Get(
 *     path="/create",
 *     description="Return a user's first and last name",
 *     @SWG\Parameter(
 *         name="firstname",
 *         in="query",
 *         type="string",
 *         description="Your first name",
 *         required=true,
 *     ),
 *     @SWG\Parameter(
 *         name="lastname",
 *         in="query",
 *         type="string",
 *         description="Your last name",
 *         required=true,
 *     ),
 *     @SWG\Response(
 *         response=200,
 *         description="OK",
 *     ),
 *     @SWG\Response(
 *         response=422,
 *         description="Missing Data"
 *     )
 * )
 */

TA-DA!

Jetzt sollten wir in der Lage sein, hier auf unser Endresultat zuzugreifen.

Das Endresultat unserer Swagger-Dokumentation und der Swagger-UI-Integration

Wenn wir nun auf unseren Routen-Endpoint klicken, können wir firstname und lastname eingeben und die GET-Anfrage durchführen.

Wie bei den meisten Tutorials gäbe es noch viel mehr über Swagger und Dokumentationen im Allgemeinen zu sagen. Daher würde ich allen Interessierten dringend das Paket auf Github ans Herz legen, um ein besseres Verständnis dafür zu bekommen, wie alles im Detail funktioniert und was es bei der Syntax bei komplexeren Anfragen zu beachten gilt. 

Danke fürs Lesen!