Verwenden Sie Swagger, um API-Dokumente in Beego automatisch zu generieren

Verwenden Sie Swagger in Beego, um API-Dokumente automatisch zu generieren

Da die Internet-Technologie immer ausgereifter wird, beginnen immer mehr Unternehmen, ihre Geschäftsmodelle digital zu transformieren, und auch APIs als wichtiger Teil der digitalen Transformation werden immer wichtiger. Bei der Entwicklung von APIs ist neben der Gewährleistung der Sicherheit und Zuverlässigkeit der API auch die Frage, wie andere Front-End- und Back-End-Entwicklungsingenieure in die Lage versetzt werden können, die von ihnen entwickelte API schnell zu verstehen und zu verwenden, ein sehr wichtiger Teil. In diesem Artikel wird erläutert, wie Sie das Swagger-Tool zum automatischen Generieren von API-Dokumenten verwenden, wenn Sie APIs mithilfe des Beego-Frameworks entwickeln, um den Anruf und die Verwendung anderer Entwicklungsingenieure zu erleichtern.

Was ist Swagger?

Swagger ist eine Open-Source-API-Spezifikation und ein Toolset, das darauf abzielt, die Entwicklung und Verwendung von APIs zu vereinfachen und zu standardisieren. Es kann automatisch interaktive Schnittstellen zwischen Entwicklern, Verbrauchern und Dokumenten generieren und bietet viele visuelle Hilfedokumentfunktionen.

Warum Swagger verwenden?

Einige APIs erfordern Dokumentation und Beschreibungen, um ihre Verwendung und ihren Aufruf zu verstehen. Mit Swagger können diese Dokumente vereinfacht und automatisch generiert werden. Durch die Verwendung des Swagger-Tools können API-Dokumente schöner, standardisierter und leichter lesbar gemacht werden, wenn sie generiert werden. Das obligatorische Format von Swagger kann Entwickler auch beim Entwerfen und Implementieren von APIs unterstützen, die standardisierten Spezifikationen entsprechen, und so Zeit und Energie sparen.

Swagger in Beego verwenden

1. Abhängigkeiten hinzufügen

Um Swagger in einem Beego-Projekt zu verwenden, müssen Sie zuerst die Abhängigkeiten der Swagger-Bibliothek zum Projekt hinzufügen. Es kann über den folgenden Befehl installiert werden:

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

2. Swagger-Kommentare bearbeiten

Im Beego-Framework verwenden wir Kommentare im Router-Code, um die API-Parameter, Anforderungstypen, Rückgabewerte und andere Informationen zu erläutern Erforderlich bei Verwendung von Swagger. Fügen Sie Swagger-Spezifikations-Tags zu diesen Kommentaren hinzu, um automatisch API-Dokumentation zu generieren.

Das Folgende ist ein einfaches Beispiel:

// @Summary  获取一个用户信息
// @Description 通过ID获取一个用户信息
// @Accept  json
// @Produce  json
// @Param   id     path    int     true        "用户ID"
// @Success 200 {object} models.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

In den Kommentaren haben wir einige spezielle Spezifikations-Tags hinzugefügt:

• @Summary: Übersicht über API-Methoden
• @Description: Detaillierte Beschreibung von API-Methoden
• @Accept: Akzeptierter Inhalt -Typtyp
• @Produzieren: Antwortinhaltstyptyp
• @Param: Anforderungsparameter, einschließlich Parametername, Speicherort, Datentyp, ob erforderlich und Beschreibung.
• @Success: HTTP-Statuscode und Rückgabewerttyp einer erfolgreichen Antwort, der auch Arrays, Strukturen und andere Informationen enthalten kann.
• @Router: Anforderungspfad und Anforderungsmethode.

Sie können bei Bedarf weitere Tags hinzufügen, um die API-Beschreibung zu ergänzen.

3. Dokumentation automatisch generieren

Nachdem wir Swagger-Spezifikationskommentare zum Code hinzugefügt haben, führen Sie den folgenden Befehl im Stammverzeichnis des Projekts aus, um API-Dokumentation zu generieren:

swag init

Dieser Befehl wird im Projektverzeichnis A docs-Ordner generiert , die generierte API-Dokumentation und statische Ressourcendateien enthält.

4. Verwenden Sie SwaggerUI, um die API-Dokumentation anzuzeigen.

Wenn wir die generierte Dokumentation direkt an die Front-End-Entwickler senden, wird dies unnötigen Druck auf sie ausüben. Um die API-Dokumentation benutzerfreundlicher und benutzerfreundlicher zu gestalten, können wir SwaggerUI zum Anzeigen der API-Dokumentation einführen.

Zuerst müssen wir die statischen SwaggerUI-Ressourcendateien in unser Projekt kopieren. Dann können wir einen Router mit dem Pfad /swagger/*any erstellen, um SwaggerUI mit unserem Projekt zu verknüpfen:

r.StaticFS("/swagger", http.Dir("docs"))

Als nächstes besuchen Sie im Browser http:/. /localhost:8080/swagger/index.html, um die automatisch generierte API-Dokumentation anzuzeigen.

Zusammenfassung

Mit Swagger in Beego können Sie die Definition von APIs durch Anmerkungen standardisieren und schöne API-Dokumente für die einfache Verwendung durch Entwickler generieren. Gleichzeitig kann die Einführung von SwaggerUI die API-Anzeige und -Interaktion weiter vereinfachen und die Entwicklung beschleunigen.

Referenzen:

https://www.cnblogs.com/wuyun-blog/p/10540875.html

https://github.com/swaggo/gin-swagger

https://github.com / Swaggo/Swag

Das obige ist der detaillierte Inhalt vonVerwenden Sie Swagger, um API-Dokumente in Beego automatisch zu generieren. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!