So verwenden Sie die OAS-basierte API-Dokumentation in PHP-PHP-Tutorial-php.cn

So verwenden Sie die OAS-basierte API-Dokumentation in PHP

WBOY

Freigeben： 2023-06-17 11:14:01

Original

1163 Leute haben es durchsucht

Mit der rasanten Entwicklung des Internets ist API (Application Programming Interface) zu einem unverzichtbaren Bestandteil geworden. Die Funktion der API besteht darin, die Interaktion und Kommunikation zwischen verschiedenen Anwendungen zu ermöglichen, um Datenaustausch und Geschäftskonnektivität zu erreichen. Mit der Zunahme und Erweiterung von APIs ist die effektive Verwaltung und Pflege von API-Dokumenten zu einem Problem geworden, das gelöst werden muss. In dieser Hinsicht hat sich die auf OAS (OpenAPI Specification) basierende API-Dokumentation zu einer effektiven Verwaltungsmethode entwickelt. Als Nächstes stellen wir die Verwendung der OAS-basierten API-Dokumentation in PHP vor.

1. Was ist OAS

OAS ist die Abkürzung für OpenAPI Specification, die auch als Swagger-Spezifikation bezeichnet werden kann. OAS ist eine Sprache zum Definieren von APIs. Sie basiert auf dem JSON- oder YAML-Format und wird zum Definieren der Spezifikationen von RESTful-APIs zum Schreiben und Generieren effektiver API-Dokumente und Client-Codes verwendet.

2. So schreiben Sie OAS-Dokumente

Sie können den Swagger-Editor zum Schreiben von OAS-Dokumenten verwenden. Gleichzeitig stellt OAS auch einige Spezifikationsanforderungen bereit, z. B. die Definition von API-Anfragen, -Antworten, -Parametern und anderen Formaten. Das Folgende ist ein grundlegendes Beispiel für das Schreiben eines API-Dokuments basierend auf OAS:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Example API
  description: "This is an example API for demonstration purposes."
paths:
  /example:
    get:
      summary: Example Endpoint
      description: "This endpoint returns an example response."
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  example_property:
                    type: string

Nach dem Login kopieren

Im OAS-Dokument müssen Sie die grundlegenden Informationen der API definieren, z. B. URL, Anforderungs- und Antwortformat usw. Das Obige ist ein einfaches Beispiel, das einen Endpunkt namens /example enthält, der ein Antwortobjekt im JSON-Format zurückgibt.

3. So verwenden Sie OAS-basierte API-Dokumente

Bevor Sie OAS-basierte API-Dokumente verwenden, müssen Sie wissen, wie OAS-Dokumente analysiert und überprüft werden. Derzeit gibt es viele Open-Source-Tools und -Bibliotheken, die Ihnen bei dieser Aufgabe helfen können, wie z. B. OpenAPI Generator, Swagger Codegen, Swagger UI usw. Hier verwenden wir die Swagger-Benutzeroberfläche, um zu demonstrieren, wie die OAS-basierte API-Dokumentation verwendet wird.

Laden Sie Swagger UI herunter und extrahieren Sie es in den öffentlichen Ordner Ihres PHP-Projekts. Sie können die neueste Version von der GitHub-Seite von Swagger UI herunterladen.
Kopieren Sie Ihr OAS-Dokument in das öffentliche Verzeichnis, in dem sich Swagger UI befindet, und nennen Sie es swagger.json.
Bearbeiten Sie die Datei index.html und ändern Sie die darin enthaltene URL in den Pfad Ihrer Datei swagger.json.
Um die Swagger-Benutzeroberfläche in PHP zu verwenden, müssen Sie lediglich den folgenden Code in Ihre PHP-Datei einfügen:

<!DOCTYPE html>
<html>
<head>
    <title>My API documentation</title>
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="swagger-ui/swagger-ui-bundle.js"></script>
    <script src="swagger-ui/swagger-ui-standalone-preset.js"></script>
    <script>
        window.onload = function() {
          const ui = SwaggerUIBundle({
            url: "./swagger.json",
            dom_id: "#swagger-ui",
            presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
            layout: "StandaloneLayout"
          })
        }
    </script>
</body>
</html>

Nach dem Login kopieren

An diesem Punkt können Sie auf Ihre Swagger-Benutzeroberfläche zugreifen, um Ihre API zu verstehen und zu testen. Die Swagger-Benutzeroberfläche generiert automatisch eine API-Dokumentation basierend auf Ihrer OAS-Dokumentation, und Sie können API-Anfragen und -Antworten in der Benutzeroberfläche testen.

4. Zusammenfassung

In diesem Artikel haben wir die Verwendung der OAS-basierten API-Dokumentation in PHP vorgestellt. Die OAS-basierte API-Dokumentation ist eine effektive Methode zur API-Dokumentenverwaltung, die uns dabei helfen kann, APIs besser zu warten und zu verwalten. Wenn Sie mehr über das Schreiben und Verwenden von OAS-Dokumenten erfahren möchten, wird empfohlen, die offizielle OAS-Dokumentation zu lesen und einige Open-Source-Tools zu verwenden, um sie zu implementieren und zu testen.

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