Verwendung von SwaggerUI zur Implementierung der API-Onlinedokumentation in Golang

Verwendung von SwaggerUI zur Implementierung der API-Onlinedokumentation in Golang

Mit dem Aufkommen moderner Anwendungsarchitektur ist API (Application Programming Interface) zur Grundkomponente moderner Webanwendungen geworden. Da die Anzahl der APIs weiter zunimmt, ist das Schreiben und Pflegen der API-Dokumentation zu einer mühsamen Aufgabe geworden. Daher ist es unbedingt erforderlich, den Schreib- und Pflegeprozess der API-Dokumentation zu vereinfachen. Swagger ist eine beliebte Lösung, die ein leistungsstarkes Dokumentationstool für Web-APIs bereitstellt. In diesem Artikel wird erläutert, wie Sie mit SwaggerUI die API-Onlinedokumentation in Golang implementieren.

Einführung in Swagger

Swagger ist eine Reihe von Open-Source-API-Erstellungstools, die Entwicklern beim Entwerfen, Erstellen, Dokumentieren und Testen von RESTful-APIs helfen können. Es enthält mehrere Tools wie Swagger Editor, Swagger UI und Swagger Codegen.

Der Swagger-Editor ist ein webbrowserbasierter Editor, der Entwicklern beim Schreiben und Bearbeiten von Swagger-Spezifikationen helfen kann. Swagger-Codegen kann automatisch Clients generieren Code.

Verwendung von SwaggerUI zur Implementierung der API-Onlinedokumentation in Golang

Golang ist eine sehr beliebte Programmiersprache. Ihre Vorteile sind eine hohe Parallelitätsleistung und ein geringer Overhead. Es verwendet leichtgewichtige Threads namens Goroutines, um Parallelität zu handhaben, und unterstützt automatisches Speicherrecycling und Garbage Collection. In Golang können Sie die Go-Swagger-Bibliothek verwenden, um die API-Onlinedokumentation zu implementieren.

1. Swagger installieren

Zuerst müssen Sie Swagger installieren, das über den folgenden Befehl installiert werden kann:

$ brew tap go-swagger/go-swagger
$ brew install go-swagger

2. Ein Golang-Projekt initialisieren

Als nächstes müssen Sie ein Golang-Projekt auf Ihrem lokalen Computer initialisieren. Erstellt ein Golang-Projekt mit dem Namen Go-Swagger-API auf Ihrem lokalen Computer mit dem folgenden Befehl:

$ mkdir Go-Swagger-API 
$ cd Go-Swagger-API 
$ go mod init Go-Swagger-API 

3. API-Definition erstellen

Um eine API-Definition zu erstellen, müssen Sie eine YAML-Datei erstellen und die API-Einstellungen darin definieren Es. In diesem Beispiel können Sie eine Datei mit dem Namen pets.yaml erstellen und den folgenden Code hinzufügen:

swagger: "2.0"
info:
  version: 1.0.0
  title: Petstore API 
produces:
- application/json
paths:
  /pets:
    get:
      summary: List all pets 
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error
    post:
      summary: Add a new pet 
      parameters:
        - in: body
          name: body
          schema:
            "$ref": "#/definitions/pet"
          required: true
      responses:
        201:
          description: Created
        500:
          description: Internal Server Error

definitions:
  pet:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      tag:
        type: string

4. API-Server-Framework generieren

Als nächstes müssen Sie das Go-Swagger-Tool verwenden, um den Code zu generieren generiert automatisch Code unter Verwendung der im vorherigen Schritt definierten Konfiguration. Geben Sie im Terminal den folgenden Befehl ein:

$ swagger generate server -A Go-Swagger-API -f pets.yaml

Dieser Befehl generiert das serverseitige Framework basierend auf der Definition in der YAML-Datei.

5. Starten Sie den API-Server

Als nächstes müssen Sie den API-Server starten und überprüfen, ob er ordnungsgemäß funktioniert. Geben Sie im Terminal den folgenden Befehl ein:

$ cd cmd/go-swagger-api-server/
$ go run main.go

Die Ausgabe sollte etwa wie folgt aussehen:

Serving Go-Swagger-API at http://127.0.0.1:8080 

Sie sollten nun in Ihrem Webbrowser auf die folgende URL zugreifen können, um zu überprüfen, ob die API funktioniert: http: //127.0.0.1 :8080/pets. http://127.0.0.1:8080/pets。

6. 集成SwaggerUI

最后一步是在API服务器中集成SwaggerUI。首先，在项目的根目录下创建一个名为swagger-ui的目录，并在其中下载SwaggerUI，可以通过下面的命令来实现：

$ mkdir swagger-ui && cd swagger-ui && wget https://github.com/swagger-api/swagger-ui/archive/v3.32.3.tar.gz && tar xfz v3.32.3.tar.gz --strip-components=1 && rm v3.32.3.tar.gz

接下来，在API服务器的main.go文件中添加以下代码：

// Setup the SwaggerUI middleware
swaggerUI := http.FileServer(http.Dir("./swagger-ui/dist"))
r.PathPrefix("/docs").Handler(http.StripPrefix("/docs", swaggerUI))

此代码将SwaggerUI中的dist目录作为静态资源文件公开，用于呈现实际的SwaggerUI。

现在，可以在浏览器中访问以下URL以查看自动生成的API文档：http://localhost:8080/docs/index.html

SwaggerUI integrieren

Der letzte Schritt besteht darin, SwaggerUI in den API-Server zu integrieren. Erstellen Sie zunächst ein Verzeichnis mit dem Namen swagger-ui im ​​Stammverzeichnis des Projekts und laden Sie SwaggerUI herunter. Dies kann durch Ausführen des folgenden Befehls erreicht werden:

rrreee🎜 Als nächstes fügen Sie den folgenden Code in die Datei main.go der API ein server:🎜rrreee🎜Dieser Code stellt das dist-Verzeichnis in SwaggerUI als statische Ressourcendatei zum Rendern der eigentlichen SwaggerUI bereit. 🎜🎜Jetzt können Sie die folgende URL in Ihrem Browser aufrufen, um die automatisch generierte API-Dokumentation anzuzeigen: http://localhost:8080/docs/index.html. 🎜🎜Fazit🎜🎜Es ist nicht schwierig, SwaggerUI zum Implementieren der API-Online-Dokumentation in Golang zu verwenden, was das Schreiben und Verwalten der API-Dokumentation sehr erleichtert. Durch die Verwendung von Swagger kann automatisch eine Dokumentation für die API generiert werden, und Back-End-Ingenieure und Front-End-Ingenieure können die API-Schnittstelle schnell verstehen. Dies vereinfacht den API-Entwicklungs-, Test- und Dokumentationsprozess erheblich und ermöglicht Entwicklern, sich mehr auf die Implementierung der Geschäftslogik zu konzentrieren. 🎜

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