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

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

Jun 03, 2023 pm 08:10 PM
golang swaggerui api文档

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
Nach dem Login kopieren

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…
}
Nach dem Login kopieren

Schritt 3: Swagger-JSON-Datei generieren

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

swag init
Nach dem Login kopieren

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
Nach dem Login kopieren

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
Nach dem Login kopieren

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;
    }
  }
}
Nach dem Login kopieren

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!

Erklärung dieser Website
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

Heiße KI -Werkzeuge

Undresser.AI Undress

Undresser.AI Undress

KI-gestützte App zum Erstellen realistischer Aktfotos

AI Clothes Remover

AI Clothes Remover

Online-KI-Tool zum Entfernen von Kleidung aus Fotos.

Undress AI Tool

Undress AI Tool

Ausziehbilder kostenlos

Clothoff.io

Clothoff.io

KI-Kleiderentferner

AI Hentai Generator

AI Hentai Generator

Erstellen Sie kostenlos Ai Hentai.

Heißer Artikel

R.E.P.O. Energiekristalle erklärten und was sie tun (gelber Kristall)
2 Wochen vor By 尊渡假赌尊渡假赌尊渡假赌
Repo: Wie man Teamkollegen wiederbelebt
4 Wochen vor By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island Abenteuer: Wie man riesige Samen bekommt
3 Wochen vor By 尊渡假赌尊渡假赌尊渡假赌

Heiße Werkzeuge

Notepad++7.3.1

Notepad++7.3.1

Einfach zu bedienender und kostenloser Code-Editor

SublimeText3 chinesische Version

SublimeText3 chinesische Version

Chinesische Version, sehr einfach zu bedienen

Senden Sie Studio 13.0.1

Senden Sie Studio 13.0.1

Leistungsstarke integrierte PHP-Entwicklungsumgebung

Dreamweaver CS6

Dreamweaver CS6

Visuelle Webentwicklungstools

SublimeText3 Mac-Version

SublimeText3 Mac-Version

Codebearbeitungssoftware auf Gottesniveau (SublimeText3)

Wie kann ich Dateien mit Golang sicher lesen und schreiben? Wie kann ich Dateien mit Golang sicher lesen und schreiben? Jun 06, 2024 pm 05:14 PM

Das sichere Lesen und Schreiben von Dateien in Go ist von entscheidender Bedeutung. Zu den Richtlinien gehören: Überprüfen von Dateiberechtigungen, Schließen von Dateien mithilfe von Verzögerungen, Validieren von Dateipfaden, Verwenden von Kontext-Timeouts. Das Befolgen dieser Richtlinien gewährleistet die Sicherheit Ihrer Daten und die Robustheit Ihrer Anwendungen.

Wie konfiguriere ich den Verbindungspool für die Golang-Datenbankverbindung? Wie konfiguriere ich den Verbindungspool für die Golang-Datenbankverbindung? Jun 06, 2024 am 11:21 AM

Wie konfiguriere ich Verbindungspooling für Go-Datenbankverbindungen? Verwenden Sie den DB-Typ im Datenbank-/SQL-Paket, um eine Datenbankverbindung zu erstellen. Legen Sie MaxOpenConns fest, um die maximale Anzahl gleichzeitiger Verbindungen festzulegen. Legen Sie ConnMaxLifetime fest, um den maximalen Lebenszyklus der Verbindung festzulegen.

Ähnlichkeiten und Unterschiede zwischen Golang und C++ Ähnlichkeiten und Unterschiede zwischen Golang und C++ Jun 05, 2024 pm 06:12 PM

Golang und C++ sind Garbage-Collected- bzw. manuelle Speicherverwaltungs-Programmiersprachen mit unterschiedlicher Syntax und Typsystemen. Golang implementiert die gleichzeitige Programmierung über Goroutine und C++ implementiert sie über Threads. Die Golang-Speicherverwaltung ist einfach und C++ bietet eine höhere Leistung. In der Praxis ist Golang-Code prägnanter und C++ bietet offensichtliche Leistungsvorteile.

Wie steil ist die Lernkurve der Golang-Framework-Architektur? Wie steil ist die Lernkurve der Golang-Framework-Architektur? Jun 05, 2024 pm 06:59 PM

Die Lernkurve der Go-Framework-Architektur hängt von der Vertrautheit mit der Go-Sprache und der Backend-Entwicklung sowie der Komplexität des gewählten Frameworks ab: einem guten Verständnis der Grundlagen der Go-Sprache. Es ist hilfreich, Erfahrung in der Backend-Entwicklung zu haben. Frameworks mit unterschiedlicher Komplexität führen zu unterschiedlichen Lernkurven.

Wie generiere ich zufällige Elemente aus einer Liste in Golang? Wie generiere ich zufällige Elemente aus einer Liste in Golang? Jun 05, 2024 pm 04:28 PM

So generieren Sie zufällige Elemente einer Liste in Golang: Verwenden Sie rand.Intn(len(list)), um eine zufällige Ganzzahl innerhalb des Längenbereichs der Liste zu generieren. Verwenden Sie die Ganzzahl als Index, um das entsprechende Element aus der Liste abzurufen.

Vergleich der Vor- und Nachteile des Golang-Frameworks Vergleich der Vor- und Nachteile des Golang-Frameworks Jun 05, 2024 pm 09:32 PM

Das Go-Framework zeichnet sich durch seine hohen Leistungs- und Parallelitätsvorteile aus, weist jedoch auch einige Nachteile auf, z. B. dass es relativ neu ist, über ein kleines Entwickler-Ökosystem verfügt und einige Funktionen fehlen. Darüber hinaus können schnelle Änderungen und Lernkurven von Framework zu Framework unterschiedlich sein. Das Gin-Framework ist aufgrund seines effizienten Routings, der integrierten JSON-Unterstützung und der leistungsstarken Fehlerbehandlung eine beliebte Wahl für die Erstellung von RESTful-APIs.

Was sind die Best Practices für die Fehlerbehandlung im Golang-Framework? Was sind die Best Practices für die Fehlerbehandlung im Golang-Framework? Jun 05, 2024 pm 10:39 PM

Best Practices: Erstellen Sie benutzerdefinierte Fehler mit klar definierten Fehlertypen (Fehlerpaket). Stellen Sie weitere Details bereit. Protokollieren Sie Fehler ordnungsgemäß. Geben Sie Fehler korrekt weiter und vermeiden Sie das Ausblenden oder Unterdrücken. Wrappen Sie Fehler nach Bedarf, um Kontext hinzuzufügen

Anweisungen zur Verwendung des Golang-Framework-Dokuments Anweisungen zur Verwendung des Golang-Framework-Dokuments Jun 05, 2024 pm 06:04 PM

Wie verwende ich die Go-Framework-Dokumentation? Bestimmen Sie den Dokumenttyp: offizielle Website, GitHub-Repository, Ressource eines Drittanbieters. Verstehen Sie die Dokumentationsstruktur: Erste Schritte, ausführliche Tutorials, Referenzhandbücher. Finden Sie die Informationen nach Bedarf: Nutzen Sie die Organisationsstruktur oder die Suchfunktion. Begriffe und Konzepte verstehen: Lesen Sie neue Begriffe und Konzepte sorgfältig durch und verstehen Sie sie. Praxisbeispiel: Erstellen Sie mit Beego einen einfachen Webserver. Weitere Go-Framework-Dokumentation: Gin, Echo, Buffalo, Fiber.

See all articles