在Golang中使用SwaggerUI進行API線上文件自動化
API（應用程式介面）的使用已經成為現代應用程式開發中的必要元素。 API讓前後端分離、微服務和雲端應用變得更容易。但是，一個好的API並不僅僅是實現了功能，而是對用戶友好和易於使用。為此，文檔化API變得越來越重要。線上文件的好處是可以在操作API之前了解它。
在本文中，我們將介紹如何使用SwaggerUI記錄API文檔以及如何在Golang中自動化此過程，以便更輕鬆地維護，提供可讀性好的文檔，方便其他團隊與合作夥伴了解您的API。
SwaggerUI是一個流行的工具，用於為API建立文檔，產生互動式API文檔，透過視覺化方式描述API，可以產生人類可讀的文檔和機器可讀的JSON或YAML。 SwaggerUI可與許多程式語言集成，包括Golang。
首先，您需要使用SwaggerUI的Golang實作－Swag。 Swag是一個自動化API文件化工具，結合了Go語言的註解和Swagger註釋，可自動產生Swagger2.0文件。
步驟1：安裝Swag
在終端機/cmd中使用以下指令下載和安裝Swag：
go get -u github.com/swaggo/swag/cmd/swag
登入後複製
步驟2：在程式碼中新增Swagger註解
#在程式碼中加入Swagger註解以描述API。
在HTTP處理程序函數上方的註解中加入Swagger註釋，例如：
// 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…
}登入後複製
步驟3：產生Swagger JSON檔案
使用下列指令在程式碼庫的根目錄中產生Swagger JSON檔：
該指令將使用程式碼中的Swagger註解並產生Swagger JSON檔。也可以在專案的Makefile中加入它。
步驟4：整合SwaggerUI
Swag使用SwaggerUI作為瀏覽器中展示API文件的前端，我們需要將SwaggerUI中的檔案靜態反向代理到我們的應用程式中。
假設我們的Golang應用程式在連接埠8080上運行。我們將使用的SwaggerUI版本是v3.31.1。我們可以透過以下方式從官方SwaggerUI GitHub頁面進行下載：
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
登入後複製
這將在本機目錄中產生swagger-ui資料夾，其中包含SwaggerUI的所有檔案。我們將使用nginx作為反向代理伺服器（您可以使用Apache，Caddy等），在終端機/cmd中使用以下命令啟動nginx：
nginx -c /path/to/nginx.conf
登入後複製
在nginx.conf檔案中，我們需要新增以下內容：
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;
}
}
}登入後複製
在上述nginx配置中，我們將靜態SwaggerUI資料夾/swagger-ui/dist目錄添加到nginx伺服器的根目錄中作為靜態文件，我們代理到localhost:8080（我們自己的應用程序）的所有請求透過轉送到由8081埠監聽的連接埠。我們透過造訪http://localhost:8081/swagger-ui/來檢視和使用SwaggerUI。
步驟5：檢視API文件
在瀏覽器中造訪http://localhost:8081/swagger-ui/，SwaggerUI應用程式將顯示出現在根目錄中的SwaggerUI static文件夾。您可以在該頁面中找到所有文件好的API清單。點選要查看的API文檔會在右側顯示。本網站提供直接在API上測試並檢視API文件的API使用者友善介面。在這個過程中，GUI展示Swagger註釋自動提取的的詳細信息，例如提供了此api的參數，body信息，Api版本，api格式等等，這將大大節省您編寫文件的時間和精力。
結論
API文件是API設計和開發過程的重要工具，因此我們需要在建置應用程式中考慮文件化API。利用自動化工具Swag，我們可以輕鬆地在Golang中進行API文件自動化。使用SwaggerUI作為視覺化工具來檢視和測試文件化的API也非常方便。這將為其他團隊和協作夥伴提供協助，並使他們更容易了解我們的API。
以上是在Golang中使用SwaggerUI進行API線上文件自動化的詳細內容。更多資訊請關注PHP中文網其他相關文章！
