博客 / 詳情

返回

Gin 實現自動生成接口文檔

自動生成接口文檔的好處

説之前，先説一下自動生成接口文檔有哪些好處？

1）節省時間和工作量：手動編寫接口文檔是一項耗時且繁瑣的任務。通過自動生成接口文檔，可以大大減少編寫文檔的時間和工作量，提高開發效率。

2）保持文檔與代碼同步：代碼和文檔往往是不同步的，當代碼發生變更時，手動更新文檔可能容易出現遺漏或錯誤。自動生成接口文檔可以保持文檔與代碼的同步，確保文檔的準確性和實時性。

3）提供一致的文檔格式：通過自動生成接口文檔，可以定義一致的文檔格式和結構，使得所有接口文檔都具有相同的風格和組織方式。這樣可以提高文檔的可讀性和易用性，減少理解和使用文檔的成本。

4）方便團隊協作和交流：自動生成的接口文檔可以作為團隊協作和交流的重要工具。團隊成員可以很方便地查閲接口文檔，瞭解接口的定義、參數、返回值等信息，從而更好地進行開發、測試和集成工作。

5）提升接口的可測試性：自動生成的接口文檔通常會包含接口的請求示例和響應示例，這些示例可以用於接口的測試和驗證。這樣可以提升接口的可測試性，減少開發人員在編寫測試代碼時的工作量。

總結：自動生成接口文檔可以大大提高開發效率、保持文檔與代碼同步、提供一致的文檔格式、方便團隊協作和交流，並提升接口的可測試性。這對於項目的開發和維護都是非常有益的。

項目使用的工具包

接下來，説一下咱們項目使用的工具包：Swag。

目前在項目中已經集成完畢，大家只要寫好註釋，執行腳本，就可以自動生成接口文檔。接口文檔地址：http://127.0.0.1:9999/swagger/index.html

為了安全起見，接口文檔地址在啓動參數 -env=pro 時，不可預覽！

在 Go 語言中，Swagger 是一種用於描述和定義 RESTful API 的規範。Go Swag 是一個用於自動生成 Swagger 文檔的工具。為了使用 Go Swag 生成 Swagger 文檔，你需要在代碼中添加相應的註釋。

以下是一些常見的 Go Swag 註釋示例：

// @Summary 創建管理員
// @Description 創建管理員
// @Tags API.admin
// @Accept application/x-www-form-urlencoded
// @Produce json
// @Param username formData string true "用户名"
// @Param mobile formData string true "手機號"
// @Success 200 {object} createResponse
// @Failure 400 {object} code.Failure
// @Router /api/admin [post]

其中：

  • @Summary 表示 API 接口的簡要説明。
  • @Description 表示 API 接口的詳細描述。
  • @Tags 表示 API 接口所屬的標籤。
  • @Accept 表示 API 接口所支持的請求格式。
  • @Produce 表示 API 接口所支持的響應格式。
  • @Param 表示 API 接口的參數，包括參數名、類型、是否必填等信息。
  • @Success 表示 API 接口的成功響應結果，包括狀態碼和返回數據類型。
  • @Failure 表示 API 接口的失敗響應結果，包括狀態碼和錯誤信息類型。
  • @Router 表示 API 接口的路由地址。

@Tags

用於對 API 接口進行標記和分類。它可以幫助組織和管理 API 接口，並在生成的 Swagger 文檔中展示接口的標籤信息。

@Tags 註釋參數用於指定 API 接口所屬的標籤或分類。該參數可以設置一個或多個值，每個值表示一個標籤，使用半角逗號,分隔。標籤可以根據業務功能、模塊或者其他自定義規則進行分類。例如，你可以使用以下標籤：Users、Orders、Products 等。

通過在 API 接口註釋中使用 @Tags 參數，可以將接口按照功能或模塊進行分類。這些標籤將在生成的 Swagger 文檔中呈現出來，方便用户瀏覽和查找相關的接口。同時，Swagger UI 也可以通過標籤進行接口的過濾和展示。

@Accept

用於指定 API 接口所支持的請求內容類型。它可以幫助生成準確的 Swagger 文檔，並向用户展示 API 接口接受的請求數據類型。

@Accept 註釋參數用於指定 API 接口接受的請求內容類型。該參數可以設置多個值，每個值表示一個請求內容類型，使用半角逗號,分隔。

常見的請求內容類型包括：

  • application/json：JSON 格式數據
  • application/xml：XML 格式數據
  • application/octet-stream：二進制數據
  • multipart/form-data：表單數據
  • text/plain：純文本數據
  • application/x-www-form-urlencoded：URL 編碼的數據

在實際使用中，你可以根據 API 接口的需求，設置不同的請求內容類型。這些註釋參數將會在生成的 Swagger 文檔中顯示出來，方便用户瞭解和使用 API 接口。

@Produce

用於指定 API 接口返回的響應內容類型。它可以幫助生成準確的 Swagger 文檔，並向用户展示 API 接口可能返回的不同數據格式。

@Produce 註釋參數用於指定 API 接口返回的響應內容類型。該參數可以設置多個值，每個值表示一個響應內容類型，使用半角逗號,分隔。

常見的響應內容類型包括：

  • application/json：JSON 格式數據
  • application/xml：XML 格式數據
  • text/plain：純文本數據
  • image/jpeg：JPEG 圖像數據
  • application/pdf：PDF 文檔數據

在實際使用中，你可以根據 API 接口的需求，設置不同的響應內容類型。這些註釋參數將會在生成的 Swagger 文檔中顯示出來，方便用户瞭解和使用 API 接口。同時，Swagger UI 也會根據這些參數提供相應的選擇和展示。

@Param

用於標識 API 接口的參數。它包含多個字段，每個字段都表示參數的不同屬性。

以下是 @Param 註釋中常用的字段類型及其詳細解釋：

  1. name：參數名

  2. in：參數位置

    常見的參數位置包括 path、query、header、formData 和 body。

    • path：路徑參數，出現在 URL 路徑中。例如，/users/{id} 中的 {id} 就是路徑參數。
    • query：查詢參數，出現在 URL 的查詢字符串中。例如，/users?name=John 中的 name 就是查詢參數。
    • header：請求頭參數，出現在 HTTP 請求的頭部信息中。
    • formData：表單數據參數，出現在 POST 請求的表單數據中。
    • body：請求體參數，出現在請求的消息體中，通常用於 POST 或 PUT 請求。

  3. type：參數類型

    常見的數據類型包括 int、string、bool、float、time.Time 等。你也可以使用自定義的結構體類型作為參數類型。

  4. required：是否必填

    true 表示必填，false 表示可選，默認為 false。

  5. description：參數描述

  6. format：參數格式

    例如，當參數類型為 string 時，可以指定其格式為 email、date-time 等。

  7. enum：枚舉值

    表示參數的取值範圍，用於限制參數的可選值。

  8. default：默認值

在實際使用中，你可以根據具體的 API 接口需求，設置不同的參數類型、位置和屬性。這些參數註釋將幫助生成準確的 Swagger 文檔，並提供給用户參考和使用。

@Router

用於指定 API 接口的路由信息，包括 HTTP 方法和路徑。

需要注意的是，在使用 @Router 參數時，需要將 HTTP 方法和路徑放在方括號內，中間使用空格分隔。同時，路徑中的路徑參數也需要使用大括號進行標記。

在 Swag 中，使用 @Router 參數來描述 API 接口的路由信息，可以讓 Swagger 自動生成 API 文檔，並且方便測試人員和開發人員快速瞭解和測試 API 接口。

@Security

用於指定 API 接口的安全需求和認證要求。通過使用 @Security 參數，可以指定 API 接口需要的安全方案，以及安全方案的作用範圍。

在實際使用中，@Security 參數通常與安全方案定義結合使用。安全方案可以包括 API 密鑰認證、基本認證、OAuth 等各種認證方式。

通過使用 @Security 參數，可以讓 Swagger 自動生成的 API 文檔中明確顯示出每個 API 接口所需要的安全認證信息，以及開發人員如何進行相應的認證操作。總之，@Security 參數在 Swag 中用於指定 API 接口的安全需求和認證要求，幫助開發人員和測試人員快速瞭解 API 接口的安全要求，以及進行相應的測試和調試。

入口註釋

入口註釋通常位於 Go 代碼文件的第一行或者緊跟在包聲明語句後面。它使用特定的格式和指令來描述 API 的基本信息、API 版本、作者、許可證等內容。這些元數據信息會被 Swag 解析並生成對應的 API 文檔。

以下是一個典型的入口註釋的示例：

// Package main provides ...
//
// @title My Awesome API
// @description This is a sample API for demonstration purposes.
// @version 1.0
// @termsOfService https://example.com/terms
// @contact.email admin@example.com
// @license.name MIT
// @host localhost:8080
// @BasePath /api/v1

在上述示例中，入口註釋是以 // 開頭的註釋塊。它包含了各種指令，以 @ 符號開頭，用於描述 API 的各種屬性。

常見的入口註釋指令包括：

  • @title：定義 API 的標題或名稱。
  • @description：描述 API 的簡要説明。
  • @version：指定 API 的版本號。
  • @termsOfService：指定服務條款的 URL。
  • @contact.email：指定聯繫人的電子郵件地址。
  • @license.name：指定 API 的許可證名稱。
  • @host：指定 API 的主機名和端口號。
  • @BasePath：指定 API 的基本路徑。

通過在入口註釋中使用這些指令，可以為整個 API 定義基本信息，並設置全局配置。Swag 將解析這些註釋並生成對應的 API 文檔，包括標題、描述、版本號、聯繫人信息等。

入口註釋是 Swag 中非常重要的一部分，它提供了定義整個 API 的基本元數據的方式，使得生成的 API 文檔更加規範和易讀。同時，這些元數據也對開發人員和測試人員提供了有用的信息，幫助他們瞭解和使用 API。

生成文檔

go install github.com/swaggo/swag/cmd/swag
swag init

文檔生成完畢後，需要重新啓動項目才會生效。

腳本化

Mac / Linux

swagger.sh

#!/bin/bash
printf "\nRegenerating swagger doc\n\n"
go install github.com/swaggo/swag/cmd/swag@v1.16.2
time swag init
printf "\nDone.\n\n"

Windows

swagger.bat

@echo off
chcp 65001
echo.
echo Regenerating swagger doc
echo.
go install github.com/swaggo/swag/cmd/swag@v1.16.2
swag init
echo.
echo Done.

執行腳本

// Mac / Linux 環境，在項目根目錄下運行 
./scripts/swagger.sh

// Windows 環境，在項目根目錄下運行
./scripts/swagger.bat

Git commit 鈎子

Git commit 鈎子是一種在執行 git commit 命令時觸發的自定義腳本或程序，可以讓開發人員在提交代碼之前或之後執行特定的操作。

Git 提供了預定義的一些鈎子點，其中包括 pre-commit 和 post-commit 鈎子，它們分別在執行提交前和提交後觸發。

pre-commit 鈎子：在執行 git commit 前觸發，可以用於在提交前進行代碼風格檢查、靜態代碼分析、單元測試等操作。如果 pre-commit 鈎子中的操作失敗（比如代碼風格不符合規範、單元測試未通過），則會阻止提交的執行。

post-commit 鈎子：在執行 git commit 後觸發，可以用於執行一些與提交相關的操作，比如發送通知、記錄提交信息到日誌、觸發持續集成/部署流程等。

通過使用這些鈎子，開發團隊可以實現一些自動化的流程，例如確保提交的代碼符合規範、自動生成文檔、觸發自動化測試、以及在提交完成後通知團隊成員等。這有助於提高代碼質量、減少人為錯誤，並促進團隊協作。

要使用這些鈎子，只需在項目的 .git/hooks 目錄下創建相應的腳本文件（如 pre-commit 或 post-commit），並賦予執行權限即可。這些腳本可以是任意可執行文件，比如 shell 腳本、Python 腳本等。當執行 git commit 時，Git 會自動觸發相應的鈎子腳本。

我們可以將「生成文檔的腳本」放到 pre-commit 鈎子中，通過在 pre-commit 鈎子中執行文檔生成命令或腳本，可以在每次提交代碼之前自動更新文檔，使得文檔與代碼保持同步。

另外，pre-commit 鈎子還具有一個優勢，即如果文檔生成過程失敗（比如生成命令報錯），它可以阻止提交的執行，確保只有在文檔生成成功的情況下才會提交代碼。

項目代碼

  • GitHub: https://github.com/xinliangnote/go-gin-api
  • 中文文檔：https://www.yuque.com/xinliangnote/go-gin-api/ngc3x5

有問題，歡迎私信我。

swagger , gin , go , 後端
user avatar cyningsun 頭像 shockerli 頭像 yinggaozhen 頭像
3 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.