Verwendung von SwaggerUI in Golang für die Automatisierung der API-Onlinedokumentation

Verwendung von SwaggerUI in Golang zur Automatisierung der API-Onlinedokumentation

Die Verwendung von APIs (Application Programming Interfaces) ist zu einem notwendigen Element in der modernen Anwendungsentwicklung geworden. Die API erleichtert die Front-End- und Back-End-Trennung sowie Microservices und Cloud-Anwendungen. Eine gute API implementiert jedoch nicht nur Funktionalität, sondern ist auch benutzerfreundlich und einfach zu verwenden. Aus diesem Grund werden dokumentierte APIs immer wichtiger. Der Vorteil der Online-Dokumentation besteht darin, dass Sie sich vor dem Betrieb mit der API vertraut machen können.

In diesem Artikel stellen wir vor, wie Sie SwaggerUI zum Aufzeichnen der API-Dokumentation verwenden und wie Sie diesen Prozess in Golang automatisieren, um die Wartung zu vereinfachen, eine lesbare Dokumentation bereitzustellen und anderen Teams und Partnern das Verständnis Ihrer API zu erleichtern.

SwaggerUI ist ein beliebtes Tool zum Erstellen von Dokumentationen für APIs, zum Generieren interaktiver API-Dokumentationen, zum visuellen Beschreiben von APIs und kann sowohl menschenlesbare Dokumentation als auch maschinenlesbares JSON oder YAML generieren. SwaggerUI lässt sich in viele Programmiersprachen integrieren, einschließlich Golang.

Zunächst müssen Sie die Golang-Implementierung von SwaggerUI – Swag verwenden. Swag ist ein automatisiertes API-Dokumentationstool, das Go-Sprachanmerkungen und Swagger-Anmerkungen kombiniert, um automatisch Swagger 2.0-Dokumente zu generieren.

Schritt 1: Swag installieren

Laden Sie Swag herunter und installieren Sie es mit dem folgenden Befehl im Terminal/cmd:

go get -u github.com/swaggo/swag/cmd/swag

Schritt 2: Fügen Sie Swagger-Anmerkungen im Code hinzu

Fügen Sie Swagger-Anmerkungen im Code hinzu, um die API zu beschreiben.

Fügen Sie im Kommentar über der HTTP-Handler-Funktion eine Swagger-Anmerkung hinzu, zum Beispiel:

// GetByID godoc
// @Summary Get user details by ID
// @Description Get user details by ID
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} model.User
// @Failure 400 {object} ErrorResponse
// @Router /users/{id} [get]
func GetByID(c *gin.Context) {
    //…code here…
}

Schritt 3: Swagger-JSON-Datei generieren

Generieren Sie die Swagger-JSON-Datei im Stammverzeichnis Ihrer Codebasis mit dem folgenden Befehl:

swag init

This Der Befehl verwendet Swagger-Anmerkungen im Code und generiert Swagger-JSON-Dateien. Sie können es auch im Makefile Ihres Projekts hinzufügen.

Schritt 4: SwaggerUI integrieren

Swag verwendet SwaggerUI als Frontend für die Anzeige von API-Dokumenten im Browser. Wir müssen die Dateien in SwaggerUI statisch in unsere Anwendung umkehren.

Angenommen, unsere Golang-Anwendung läuft auf Port 8080. Die Version von SwaggerUI, die wir verwenden werden, ist v3.31.1. Wir können es von der offiziellen SwaggerUI GitHub-Seite herunterladen:

curl -L https://github.com/swagger-api/swagger-ui/archive/v3.31.1.tar.gz -o swagger-ui.tar.gz
tar -xf swagger-ui.tar.gz

Dadurch wird der Ordner swagger-ui im ​​lokalen Verzeichnis generiert, der alle Dateien von SwaggerUI enthält. Wir werden Nginx als Reverse-Proxy-Server verwenden (Sie können Apache, Caddy usw. verwenden). Starten Sie Nginx mit dem folgenden Befehl im Terminal/cmd:

nginx -c /path/to/nginx.conf

In der Datei nginx.conf müssen wir Folgendes hinzufügen:

http {
  server {
    listen 8081; # 访问静态文件的端口
    server_name _;
    root /path/to/swagger-ui/dist;

    location / {
      try_files $uri $uri/ @go;
    }

    location @go {
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_pass http://127.0.0.1:8080; # 代理请求的端口
    }

    location /swagger-ui/ {
      try_files $uri $uri/ =404;
    }
  }
}

In der obigen Nginx-Konfiguration fügen wir den statischen SwaggerUI-Ordner /swagger-ui/dist als statische Dateien zum Stammverzeichnis des Nginx-Servers hinzu. Wir leiten alle Anfragen an localhost:8080 (unsere eigene Anwendung) weiter, indem wir sie an Port weiterleiten 8081 ist der Abhörport. Wir sehen und verwenden SwaggerUI, indem wir http://localhost:8081/swagger-ui/ besuchen.

Schritt 5: API-Dokumentation anzeigen

Besuchen Sie http://localhost:8081/swagger-ui/ in Ihrem Browser. Die SwaggerUI-Anwendung zeigt den statischen SwaggerUI-Ordner im Stammverzeichnis an. Eine Liste aller gut dokumentierten APIs finden Sie auf dieser Seite. Klicken Sie auf die API-Dokumentation, die Sie anzeigen möchten, um sie rechts anzuzeigen. Die Website bietet eine benutzerfreundliche API-Schnittstelle zum Testen und Anzeigen der API-Dokumentation direkt auf der API. Während dieses Vorgangs zeigt die GUI die detaillierten Informationen an, die automatisch durch Swagger-Anmerkungen extrahiert werden, wie z. B. die Bereitstellung der Parameter dieser API, Körperinformationen, API-Version, API-Format usw. Dadurch sparen Sie viel Zeit und Energie beim Schreiben von Dokumenten.

Fazit

API-Dokumentation ist ein wichtiges Werkzeug im API-Design- und Entwicklungsprozess, daher müssen wir dokumentierte APIs beim Erstellen von Anwendungen berücksichtigen. Mit dem Automatisierungstool Swag können wir die API-Dokumentation in Golang einfach automatisieren. Es ist auch sehr praktisch, SwaggerUI als Visualisierungstool zum Anzeigen und Testen dokumentierter APIs zu verwenden. Dies wird anderen Teams und Kooperationspartnern helfen und ihnen das Verständnis unserer API erleichtern.

Das obige ist der detaillierte Inhalt vonVerwendung von SwaggerUI in Golang für die Automatisierung der API-Onlinedokumentation. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!