So generieren Sie API-Dokumentation mit Swagger in PHP

Mit der kontinuierlichen Weiterentwicklung von Webanwendungen ist API zu einem der Standards für die moderne Webanwendungsentwicklung geworden. Da jedoch die Anzahl und Komplexität der APIs zunimmt, wird auch deren Pflege und Dokumentation immer komplexer. Um dieses Problem zu lösen, wurde Swagger ins Leben gerufen. Es handelt sich um ein Tool zum Generieren von API-Dokumentationen, das Entwicklern die Wartung und Dokumentation von APIs erleichtert und gleichzeitig visuelle Dokumentation und verschiedene andere Funktionen bereitstellt. In diesem Artikel besprechen wir, wie man API-Dokumentation mit Swagger in PHP generiert.

Zuerst müssen wir Swagger installieren. Es gibt viele Versionen und Implementierungen von Swagger, aber wir werden hier Swagger-php verwenden, eine Open-Source-PHP-Bibliothek, die die Integration von Swagger in PHP-Code erleichtert. Wir können Swagger-php mit Composer in unserem Projekt installieren:

composer require zircote/swagger-php

Sobald wir Swagger-php installiert haben, können wir mit dem Schreiben der Swagger-Spezifikation für unsere API beginnen. Eine Swagger-Spezifikation ist eine JSON- oder YAML-Datei, die alle Details einer API beschreibt, einschließlich Endpunkt-URLs, Anforderungs- und Antwortparameter, Datenmodell und Fehlercodes. In Swagger-php können wir PHP-Annotationen verwenden, um Spezifikationen zu schreiben. Sehen wir uns ein einfaches Beispiel an:

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */

In diesem Beispiel haben wir die @OA-Annotation verwendet, um die Swagger-Spezifikation zu schreiben. @OA ist ein Namespace in der Swagger-php-Bibliothek, der zum Definieren verschiedener Arten von Swagger-Elementen wie Info, Get, Response und Parameter verwendet wird. Wir können die Annotation @OAInfo verwenden, um die grundlegenden Informationen der API zu beschreiben, wie z. B. Titel und Version. In der @OAGet-Annotation definieren wir zwei Endpunkte: /users und /users/{id}. Wir beschreiben die Anforderungsparameter und Antworten und geben Erfolgs- und Fehlerantwortcodes an. Dies ist nur ein kleines Beispiel, aber Sie können mithilfe anderer @OA-Annotationen komplexere Swagger-Spezifikationen schreiben und sogar die Authentifizierung und Autorisierung der API beschreiben.

Sobald wir unsere Swagger-Spezifikation geschrieben haben, können wir sie mit Swagger-php in ein visuelles Dokument umwandeln. Hierfür können wir Swagger-ui verwenden, eine HTML-, CSS- und JavaScript-Bibliothek zum Rendern von Swagger-Spezifikationen. Wir können das Swagger-ui-php-Paket in PHP verwenden, um Swagger-ui zu integrieren. Wir können Swagger-ui-php mit Composer in unserem Projekt installieren:

composer require swagger-api/swagger-ui

Sobald wir Swagger-ui-php installiert haben, können wir Swagger-ui in unsere PHP-Anwendung integrieren. Wir können unserem HTML-Code die folgende Zeile hinzufügen, um Swagger-ui zu laden:

<link rel="stylesheet" type="text/css" href="/vendor/swagger-api/swagger-ui/dist/swagger-ui.css">
<div id="swagger-ui"></div>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-bundle.js"></script>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.onload = function() {
    // 使用来自后端的Swagger JSON文件构造请求
    SwaggerUIBundle({
      url: "/api/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset // 用于额外的UI依赖
      ],
      layout: "StandaloneLayout"
    })
  }
</script>

In diesem Beispiel laden wir die CSS- und JavaScript-Dateien von Swagger-ui und rendern sie in einer Datei, die die ID „swagger-ui“ enthält DIV-Element. Wir verwenden JavaScript-Code, um die Swagger-JSON-Datei aus dem Backend zu laden und verwenden SwaggerUIBundle, um sie in ein schönes Dokument umzuwandeln.

Damit Swagger-ui schließlich unsere Swagger-Spezifikation laden kann, müssen wir unserer Anwendung eine Route hinzufügen, die die Swagger-JSON-Datei zurückgibt.

use OpenApiAnnotations as OA;

$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

// 或者用这种方式

/**
 * @OAServer(url="http://localhost:8000")
 */

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */
$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

In diesem Beispiel verwenden wir im Gegensatz zum vorherigen Beispiel OpenApi-Annotationen, um die Swagger-Spezifikation zu schreiben. Wir haben auch eine Route hinzugefügt, um die Swagger-JSON-Datei zurückzugeben. Wir verwenden die OpenApiscan-PHP-Funktion, um unseren Routenordner zu scannen und die API-Definition in ein Swagger-JSON-Objekt zu konvertieren, das dann in einen JSON-String umgewandelt und an den Client zurückgegeben wird.

In diesem Artikel haben wir gelernt, wie man API-Dokumentation in PHP mit Swagger-php und Swagger-ui generiert. Da die Anzahl und Komplexität unserer APIs zunimmt, kann Swagger uns dabei helfen, sie einfacher zu verwalten und zu dokumentieren und gleichzeitig eine visuelle API-Dokumentation und verschiedene andere Funktionen bereitzustellen. Durch die Verwendung von PHP-Annotationen zum Schreiben von Swagger-Spezifikationen können wir das manuelle Schreiben von Dokumentation vermeiden und unseren Code klarer und einfacher zu warten gestalten.

Das obige ist der detaillierte Inhalt vonSo generieren Sie API-Dokumentation mit Swagger in PHP. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!