Mit der rasanten Entwicklung des Internets ist API (Application Programming Interface) zu einem Standardverfahren für die moderne Anwendungsentwicklung geworden. API bezieht sich auf eine Reihe von Schnittstellen, die es Anwendungen ermöglichen, Daten und Funktionen auszutauschen, sodass Anwendungen bequem und schnell miteinander interagieren können.
Nachdem wir eine API erstellt haben, müssen wir eine detaillierte Dokumentation für die API schreiben, um anderen Entwicklern die Nutzung unserer API zu erleichtern. Allerdings ist das manuelle Schreiben der API-Dokumentation eine zeit- und energieaufwendige Aufgabe, weshalb der Einsatz automatisierter Tools für die API-Dokumentationserstellung sehr notwendig und effektiv ist.
In diesem Artikel erfahren Sie, wie Sie PHP und Swagger für die API-Dokumentgenerierung verwenden.
1. Was ist Swagger?
Swagger ist eine Spezifikation zur Beschreibung und Definition von RESTful APIs. Es kann zum Generieren einer für Menschen lesbaren Dokumentation sowie als Codegenerator zum Generieren von clientseitigem und serverseitigem Code verwendet werden. Swagger kann auch zum Testen und Debuggen von APIs verwendet werden.
2. Swagger-Installation und -Konfiguration
Um Swagger zum Generieren von API-Dokumenten zu verwenden, müssen Sie es zuerst installieren. Wir können Composer verwenden, um Swagger zu installieren. Composer ist ein Abhängigkeitsmanager für PHP und kann die neueste Version von Swagger herunterladen.
Verwenden Sie den folgenden Befehl, um Swagger zu installieren:
composer require "swagger-api/swagger-ui:^3.50"
Nach dem Login kopieren
Nachdem die Installation abgeschlossen ist, müssen wir einige Konfigurationen für Swagger vornehmen. Erstellen Sie eine swagger.php-Datei im Stammverzeichnis des Projekts und fügen Sie den folgenden Code hinzu:
<?php
require_once(__DIR__ . '/vendor/autoload.php');
use OpenApiAnnotations as OA;
$swagger = OpenApiscan('/path/to/your/controllers');
header('Content-Type: application/json');
echo $swagger;Nach dem Login kopieren
Im obigen Code sollte /path/to/your/controllers durch Ihren eigenen Controller-Pfad ersetzt werden. Darüber hinaus müssen wir auch einige Konfigurationen zur Datei „composer.json“ hinzufügen:
"config": {
"platform": {
"php": "7.4"
}
},
"autoload": {
"classmap": [
"app/",
"database/",
"routes/",
"tests/"
]
},
"require": {
"php": "^7.4",
"laravel/framework": "^8.40",
"tymon/jwt-auth": "^1.0",
"doctrine/dbal": "^2.13",
"swagger-api/swagger-ui": "^3.50"
},
"require-dev": {
"facade/ignition": "^2.5",
"fzaninotto/faker": "^1.9.1",
"mockery/mockery": "^1.4.2",
"nunomaduro/collision": "^6.0",
"phpunit/phpunit": "^9.3.3"
},Nach dem Login kopieren
3. Verwenden Sie Swagger, um API-Dokumente zu generieren
Nach der Installation und Konfiguration von Swagger können wir damit beginnen, es zum Generieren von API-Dokumenten zu verwenden. Wir können den folgenden Befehl verwenden, um eine API-Dokumentation zu generieren:
php swagger.php > swagger.json
Nach dem Login kopieren
Im obigen Befehl ist swagger.php die gerade erstellte Swagger-Konfigurationsdatei und swagger.json die von uns generierte API-Dokumentationsdatei.
4. Verwenden Sie die Swagger-Benutzeroberfläche, um API-Dokumente anzuzeigen.
Nachdem wir das API-Dokument generiert haben, hoffen wir, es anzuzeigen, damit andere es anzeigen können. Sie können die Swagger-Benutzeroberfläche verwenden, um die API-Dokumentation anzuzeigen. Swagger UI ist eine JavaScript-Bibliothek zur Anzeige von RESTful-API-Informationen und deren von Swagger beschriebener Implementierung.
Wir können der Datei index.php im öffentlichen Verzeichnis den folgenden Inhalt hinzufügen:
require_once(__DIR__ . '/../vendor/autoload.php');
$swagger = file_get_contents(__DIR__ . '/../swagger.json');
$swaggerData = json_decode($swagger, true);
?>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.min.css" >
<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="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"> </script>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "<?php echo '/swagger.json'; ?>",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}
</script>
</body>
</html>Nach dem Login kopieren
Im obigen Code verwenden wir die JavaScript-Bibliothek von Swagger UI, über die das generierte API-Dokument als schöne HTML-Seite dargestellt werden kann Die Form entfaltet sich.
Eine Beispielseite mit der API-Dokumentation ist unten dargestellt:
5. Fazit
Mit Swagger kann die API-Dokumentation einfach generiert und verwaltet werden. In diesem Artikel wird erläutert, wie Sie PHP und Swagger zum Generieren von API-Dokumenten verwenden. Zu den Schritten gehören die Installation und Konfiguration von Swagger, die Verwendung von Swagger zum Generieren von API-Dokumenten und die Verwendung der Swagger-Benutzeroberfläche zum Anzeigen von API-Dokumenten. Ich glaube, dass Leser nach der Einführung in diesem Artikel problemlos Swagger verwenden können, um ihre eigenen API-Dokumente zu generieren.
Das obige ist der detaillierte Inhalt vonSo verwenden Sie PHP und Swagger für die API-Dokumentationsgenerierung. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!
