在Golang中使用SwaggerUI進行API線上文件自動化

在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檔：

swag init

該指令將使用程式碼中的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中文網其他相關文章！