suchen

Heim >Backend-Entwicklung >PHP-Tutorial >PHP-Entwicklung: So verwenden Sie Swagger zur Pflege der API-Dokumentation

PHP-Entwicklung: So verwenden Sie Swagger zur Pflege der API-Dokumentation

WBOY
WBOYOriginal
2023-06-15 09:37:171008Durchsuche

Mit der rasanten Entwicklung des Internets ist die Web-API zum Kern der Unterstützung offener Anwendungen geworden. Die Skalierbarkeit und Wiederverwendbarkeit von APIs machen sie zu einem wichtigen Werkzeug für den Datenaustausch und die Zusammenarbeit zwischen verschiedenen Systemen. Entwickler stehen jedoch häufig vor der Frage: Wie pflegt man die API-Dokumentation und stellt die API-Zuverlässigkeit sicher?

Swagger ist ein Open-Source-Framework, das eine Komplettlösung für API-Design, Dokumentation, Tests und Bereitstellung bietet. In diesem Artikel wird erläutert, wie Sie mit Swagger die API-Dokumentation verwalten und vorhandene APIs besser verwalten und warten können.

1. Grundkonzepte von Swagger

Swagger erstellt und dokumentiert APIs über JSON- oder YAML-Spezifikationsdateien, die die API beschreiben. Diese Datei wird als Swagger-Spezifikation bezeichnet.

Swagger-Spezifikationsdatei enthält die folgenden Konzepte:

  1. Pfad: API-Pfad ist die Kennung der Ressource. Beispielsweise steht /users für alle Benutzer und /users/{id} für einen Benutzer.
  2. Methode: Eine HTTP-Methode wie GET, PUT, POST, DELETE und HEAD.
  3. Parameter: Anforderungsparameter (HTTP-Anforderungstext, URL-Pfad und/oder Abfragezeichenfolgenparameter).
  4. Antwort: HTTP-Antwortstruktur, Statuscode und Antworttexttyp (HTTP-Antworttext).
  5. Modell: Struktur von Data Transfer Object (DTO) und Response Object.
  6. Tags: API-Ressourcen logisch gruppieren, um das Lesen zu erleichtern.

2. Verwendung von Swagger

  1. Swagger UI installieren

Swagger UI ist ein Open-Source-Tool, mit dem wir Swagger-Spezifikationsdateien in einer interaktiven Oberfläche anzeigen können. Sein Hauptzweck besteht darin, eine klare und interaktive Dokumentation bereitzustellen und uns das Testen und Debuggen der API zu ermöglichen.

Installieren Sie die Swagger-Benutzeroberfläche mit dem folgenden Befehl: 

npm install swagger-ui-dist
  1. Schreiben Sie die Swagger-Spezifikationsdatei.

Schreiben Sie die Swagger-Spezifikationsdatei, um den Pfad, die Methode, die Parameter, die Antwort und andere Informationen unserer API zu beschreiben.

Hier ist ein Beispiel: 

swagger: '2.0'
info:
  title: User API Root
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      description: Returns all users
      produces:
        - application/json
      responses:
        200:
          description: A list of user names
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 123
              name:
                type: string
                example: John Doe

In diesem Beispiel definieren wir einen API-Pfad „/users“ und eine GET-Methode, die als Antwort ein Array von JSON-Objekten zurückgibt, die „id“ und „name“ enthalten.

  1. Integrieren Sie die Swagger-Benutzeroberfläche

Integrieren Sie die Swagger-Benutzeroberfläche in Ihre Webanwendung, um Ihre Swagger-Spezifikationsdatei anzuzeigen. Fügen Sie Ihrer Webseite den folgenden HTML-Code hinzu: 

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "https://api.example.com/swagger",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
    }
  </script>
</body>
</html>

In diesem Beispiel laden wir die Swagger-Benutzeroberfläche in eine HTML-Datei und übergeben die URL-Adresse der Swagger-Spezifikationsdatei an das SwaggerUIBundle, um die API-Dokumentation zu rendern.

  1. APIs testen und debuggen

Verwenden Sie die Swagger-Benutzeroberfläche, um APIs in Webanwendungen zu testen und zu debuggen.

Über die Swagger-Benutzeroberfläche können wir:

  • Die Schnittstellendokumentation anzeigen.
  • Automatisieren Sie Tests und überprüfen Sie die API-Antwortergebnisse.
  • Debug-API beim Generieren von Codeausschnitten.

Zusammenfassung

Swagger ist ein hervorragendes Framework, das Entwicklern eine Komplettlösung für API-Design, Dokumentation, Tests und Bereitstellung bieten kann. Mit Swagger können wir bestehende APIs besser verwalten und warten. Dies ist auch eine der besten Methoden im Rahmen des zentralisierten Entwicklungsmodells.

Das obige ist der detaillierte Inhalt vonPHP-Entwicklung: So verwenden Sie Swagger zur Pflege der API-Dokumentation. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!

php json html 标识符 字符串 接口 delete 对象 http ui 自动化
Stellungnahme：
Der Inhalt dieses Artikels wird freiwillig von Internetnutzern beigesteuert und das Urheberrecht liegt beim ursprünglichen Autor. Diese Website übernimmt keine entsprechende rechtliche Verantwortung. Wenn Sie Inhalte finden, bei denen der Verdacht eines Plagiats oder einer Rechtsverletzung besteht, wenden Sie sich bitte an admin@php.cn
Vorheriger Artikel：So verwenden Sie PHP und Selenium, um die Entwicklung und Praxis automatisierter Webcrawler abzuschließenNächster Artikel：So verwenden Sie PHP und Selenium, um die Entwicklung und Praxis automatisierter Webcrawler abzuschließen

In Verbindung stehende Artikel

Mehr sehen