開箱即用的 GoWind Admin｜風(fēng)行，企業(yè)級(jí)前后端一體中后臺(tái)框架：集成 Swagger UI 打造交互式 API 文檔

開箱即用的 GoWind Admin｜風(fēng)行，企業(yè)級(jí)前后端一體中后臺(tái)框架：集成 Swagger UI 打造交互式 API 文檔

在企業(yè)級(jí)中后臺(tái)系統(tǒng)開發(fā)中，接口調(diào)試、測(cè)試與文檔同步始終是困擾前后端團(tuán)隊(duì)的核心痛點(diǎn)：接口變更后文檔未及時(shí)更新、手動(dòng)編寫文檔效率低下、調(diào)試工具切換繁瑣等問題，嚴(yán)重影響開發(fā)協(xié)作效率。而 OpenAPI 規(guī)范（原 Swagger 規(guī)范）及其配套工具 Swagger UI，正是解決這些問題的最優(yōu)解之一。

筆者在使用 Python 生態(tài)的 FastAPI 框架時(shí)，發(fā)現(xiàn)其內(nèi)置的 Swagger UI 體驗(yàn)極佳——開發(fā)者可直接通過 http://127.0.0.1:8000/docs 訪問交互式 API 文檔，實(shí)現(xiàn)接口可視化調(diào)試與測(cè)試，無需額外部署工具。受此啟發(fā)，我們將這一方案借鑒到 GoWind Admin（基于 Kratos 框架的企業(yè)級(jí)前后端一體中后臺(tái)框架）中，實(shí)現(xiàn)了 API 文檔的自動(dòng)化生成與嵌入式訪問。

一、核心概念：OpenAPI 與 Swagger 的關(guān)系

很多開發(fā)者會(huì)混淆 OpenAPI 和 Swagger，其實(shí)二者是「規(guī)范」與「實(shí)現(xiàn)工具集」的關(guān)系，明確這一點(diǎn)是后續(xù)集成的基礎(chǔ)。

1.1 什么是 OpenAPI？—— API 設(shè)計(jì)的全球標(biāo)準(zhǔn)

OpenAPI 是一套用于設(shè)計(jì)、描述 RESTful API 的開放標(biāo)準(zhǔn)（并非工具），其核心價(jià)值在于標(biāo)準(zhǔn)化 API 的設(shè)計(jì)規(guī)范，確保 API 具備良好的可讀性、可擴(kuò)展性與安全性。遵循該標(biāo)準(zhǔn)的 API 可實(shí)現(xiàn)：

  • 跨團(tuán)隊(duì)協(xié)作標(biāo)準(zhǔn)化：前后端、測(cè)試、運(yùn)維團(tuán)隊(duì)基于同一套規(guī)范溝通，減少理解偏差；
  • 自動(dòng)化流程支撐：為后續(xù)的文檔生成、接口測(cè)試、客戶端 SDK 生成提供結(jié)構(gòu)化數(shù)據(jù)基礎(chǔ)；
  • 兼容性與可維護(hù)性：API 版本迭代、跨系統(tǒng)集成時(shí)具備統(tǒng)一的約束，降低維護(hù)成本。

OpenAPI 最初名為 Swagger 規(guī)范，由 Swagger 團(tuán)隊(duì)提出，后捐贈(zèng)給 Linux 基金會(huì)并更名為 OpenAPI。如需深入學(xué)習(xí)規(guī)范細(xì)節(jié)，可參考 [OpenAPI 規(guī)范（中文版）][2]。

1.2 什么是 Swagger？—— OpenAPI 規(guī)范的落地工具集

OpenAPI 僅定義規(guī)范，手動(dòng)編寫符合規(guī)范的文檔（如 JSON/YAML 格式）繁瑣且易出錯(cuò)。Swagger 則是一套實(shí)現(xiàn)了 OpenAPI 規(guī)范的工具集，旨在降低 API 開發(fā)與管理的門檻。其核心工具包括：

  • Swagger Editor：瀏覽器端編輯器，支持實(shí)時(shí)編寫 OpenAPI 規(guī)范并預(yù)覽文檔；
  • Swagger UI：核心工具，可將 OpenAPI 規(guī)范（JSON/YAML）動(dòng)態(tài)生成交互式文檔，支持在線調(diào)試接口；
  • Swagger Codegen：根據(jù) OpenAPI 規(guī)范自動(dòng)生成多語言客戶端 SDK、服務(wù)器存根代碼；
  • Swagger Inspector：免費(fèi) API 測(cè)試工具，支持驗(yàn)證 API 并反向生成 OpenAPI 規(guī)范；
  • SwaggerHub：團(tuán)隊(duì)級(jí) API 設(shè)計(jì)與文檔管理平臺(tái)，支持協(xié)作編輯與版本控制。

Swagger 官網(wǎng)：https://swagger.io/，其中 Swagger UI 是我們本次集成的核心組件。

二、Kratos 集成 Swagger UI 的核心思路

Kratos 框架基于 Protobuf（IDL 語言）和 gRPC 設(shè)計(jì) API，因此集成 Swagger UI 的核心邏輯是：

  1. 通過工具從 Protobuf 定義生成符合 OpenAPI 規(guī)范的 JSON/YAML 文檔；
  2. 將生成的 OpenAPI 文檔嵌入到 Kratos 服務(wù)中（避免額外部署文檔服務(wù)）；
  3. 在 Kratos HTTP 服務(wù)中集成 Swagger UI，使其加載嵌入式的 OpenAPI 文檔，提供交互式訪問。

下面我們按步驟拆解具體實(shí)現(xiàn)過程。

三、第一步：從 Protobuf 生成 OpenAPI 文檔

Protobuf 是 Kratos 定義 API 的基礎(chǔ)，我們需要通過 protoc 插件將 Protobuf 文件轉(zhuǎn)換為 OpenAPI 規(guī)范文檔。目前主流的 Go 語言插件有兩個(gè)，分別支持 OpenAPI v2 和 v3 版本（推薦 v3，功能更強(qiáng)大、規(guī)范更完善）。

3.1 安裝 OpenAPI 生成插件

通過 go install 安裝兩個(gè)核心插件：

# OpenAPI v2 生成器（兼容舊版 Swagger UI）
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

# OpenAPI v3 生成器（推薦，功能更完善）
go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest

3.2 直接通過 protoc 生成文檔（基礎(chǔ)方式）

安裝完成后，可直接通過 protoc 命令生成文檔，核心參數(shù)說明：

  • --proto_path=.：指定 Protobuf 文件所在目錄；
  • --openapiv2_out/--openapi_out：指定輸出目錄與路徑規(guī)則（如 paths=source_relative 表示按源文件相對(duì)路徑輸出）；
  • --openapiv2_opt/--openapi_opt：額外配置（如 JSON 字段命名規(guī)則、日志輸出等）。

生成 OpenAPI v2 JSON 文檔：

protoc --proto_path=. \
    --openapiv2_out=paths=source_relative:../docs \  # 輸出到上級(jí) docs 目錄
    --openapiv2_opt logtostderr=true \              # 開啟日志輸出
    --openapiv2_opt json_names_for_fields=true \    # JSON 字段名使用蛇形命名（如 user_name）
    ./*.proto

生成 OpenAPI v3 YAML 文檔（推薦）：

protoc --proto_path=. \
    --openapi_out=naming=json,paths=source_relative:../docs \  # 修復(fù)原文參數(shù)錯(cuò)誤，用逗號(hào)分隔配置
    ./*.proto

3.3 工程化生成：使用 Buf 替代原生 protoc

直接使用 protoc 命令存在諸多問題：多文件依賴管理復(fù)雜、參數(shù)重復(fù)輸入、團(tuán)隊(duì)協(xié)作規(guī)范不統(tǒng)一。推薦使用 Buf.Build 工具進(jìn)行工程化管理，它提供了 Protobuf 語法檢查、依賴管理、批量生成等功能。

3.3.1 安裝 Buf

go install github.com/bufbuild/buf/cmd/buf@latest

3.3.2 配置 Buf 生成規(guī)則

Buf 需通過三個(gè)核心配置文件管理生成流程（詳細(xì)配置可參考 Buf 官方文檔），此處重點(diǎn)關(guān)注 OpenAPI 生成相關(guān)的配置：在 Protobuf 文件同級(jí)目錄創(chuàng)建 buf.openapi.gen.yaml，配置 OpenAPI 生成規(guī)則：

# buf.openapi.gen.yaml：OpenAPI 生成專屬配置
version: v1
managed:
  enabled: false  # 關(guān)閉自動(dòng)管理依賴（根據(jù)項(xiàng)目實(shí)際需求調(diào)整）
plugins:
  # 生成 OpenAPI v3 YAML 文檔（后臺(tái) API 示例）
  - name: openapi
    out: ./app/admin/service/cmd/server/assets  # 輸出到服務(wù) assets 目錄（便于后續(xù)嵌入）
    opt:
      - naming=json  # 字段名使用 JSON 風(fēng)格（蛇形命名）
      - depth=2      # 嵌套字段解析深度（避免過度嵌套導(dǎo)致文檔冗余）
      - paths=source_relative  # 按源文件相對(duì)路徑生成文件

3.3.3 執(zhí)行 Buf 生成命令

在項(xiàng)目根目錄執(zhí)行以下命令，即可按配置生成 OpenAPI v3 文檔：

# 生成指定目錄的 Protobuf 對(duì)應(yīng)的 OpenAPI 文檔
buf generate --path api/admin/service/v1 \
    --template api/admin/service/v1/buf.openapi.gen.yaml

生成成功后，會(huì)在 ./app/admin/service/cmd/server/assets 目錄下生成 openapi.yaml 文件。

四、第二步：將 OpenAPI 文檔嵌入 Kratos 服務(wù)

為了避免單獨(dú)部署 OpenAPI 文檔服務(wù)，我們利用 Go 1.16+ 提供的 //go:embed 指令，將 openapi.yaml 文件嵌入到 Kratos 服務(wù)的二進(jìn)制文件中，實(shí)現(xiàn)「文檔與服務(wù)一體部署」。

4.1 編寫嵌入代碼

在 ./app/admin/service/cmd/server/assets 目錄下創(chuàng)建 assets.go 文件：

package assets

import _ "embed"

//go:embed openapi.yaml
// OpenApiData 嵌入的 OpenAPI v3 文檔數(shù)據(jù)（二進(jìn)制格式）
var OpenApiData []byte

通過 //go:embed openapi.yaml 指令，Go 編譯器會(huì)在構(gòu)建時(shí)將 openapi.yaml 文件內(nèi)容寫入 OpenApiData 變量，后續(xù)可直接在代碼中讀取。

五、第三步：集成 Swagger UI 到 Kratos 服務(wù)

Kratos 官方曾提供 swagger-api 項(xiàng)目，但目前已歸檔，且僅支持 OpenAPI v2，存在文檔讀取不穩(wěn)定等問題。為此，筆者封裝了 kratos-swagger-ui 庫，專門適配 Kratos 框架，支持 OpenAPI v3，且集成簡(jiǎn)單。

5.1 安裝集成庫

go get -u github.com/tx7do/kratos-swagger-ui

5.2 在 Kratos HTTP 服務(wù)中注冊(cè) Swagger UI

在 Kratos 服務(wù)的 HTTP 服務(wù)器初始化代碼中，調(diào)用 kratos-swagger-ui 庫的注冊(cè)方法，加載嵌入式的 OpenAPI 文檔：

package server

import (
    rest "github.com/go-kratos/kratos/v2/transport/http"
    swaggerUI "github.com/tx7do/kratos-swagger-ui"

    "kratos-cms/app/admin/service/cmd/server/assets"
)

func NewRESTServer() *rest.Server {
    srv := CreateRestServer()

    swaggerUI.RegisterSwaggerUIServerWithOption(
        srv,
        swaggerUI.WithTitle("Admin Service"),
        swaggerUI.WithMemoryData(assets.OpenApiData, "yaml"),
    )
}

5.3 自動(dòng)化構(gòu)建與運(yùn)行

為了簡(jiǎn)化「生成文檔 + 啟動(dòng)服務(wù)」的流程，我們將相關(guān)命令寫入 Makefile，實(shí)現(xiàn)一鍵執(zhí)行：

# Makefile
.PHONY: api openapi run

# 生成 Protobuf 對(duì)應(yīng)的 Go 代碼（gRPC + HTTP 網(wǎng)關(guān)）
api:
        buf generate

# 生成所有服務(wù)的 OpenAPI v3 文檔
openapi:
        # 生成后臺(tái)服務(wù) API 文檔
        buf generate --path api/admin/service/v1 --template api/admin/service/v1/buf.opena API 文檔（如有）
        buf generate --path api/front/service/v1 --template api/front/service/v1/buf.openapi.gen.yaml

# 一鍵生成代服務(wù)
run: api openapi
        @echo "啟動(dòng) Admin 服務(wù)..."
        @go run ./cmd/server -conf ./configs碼、文檔并啟動(dòng)pi.gen.yaml
        # 生成前臺(tái)服務(wù)

執(zhí)行以下命令即可完成全流程：

# 僅生成 OpenAPI 文檔
make openapi

# 生成代碼、文檔并啟動(dòng)服務(wù)
make run

六、驗(yàn)證集成效果

啟動(dòng) Kratos 服務(wù)后，若 HTTP 服務(wù)端口為 8080，可通過以下鏈接訪問 Swagger UI：

訪問后可看到：

  • 所有 Protobuf 定義的 API 接口按模塊分類展示；
  • 支持在線填寫請(qǐng)求參數(shù)，點(diǎn)擊「Try it out」直接調(diào)試接口；
  • 自動(dòng)展示響應(yīng)示例、狀態(tài)碼說明，無需手動(dòng)編寫文檔。

七、項(xiàng)目代碼與參考資料

7.1 完整項(xiàng)目代碼

7.2 擴(kuò)展參考資料

八、總結(jié)

通過本文的方案，我們實(shí)現(xiàn)了 Kratos 框架與 Swagger UI 的深度集成，核心優(yōu)勢(shì)在于：

  1. 自動(dòng)化文檔生成：從 Protobuf 定義一鍵生成 OpenAPI 文檔，避免手動(dòng)編寫與更新；
  2. 嵌入式部署：文檔與服務(wù)一體部署，無需額外維護(hù)文檔服務(wù)；
  3. 交互式調(diào)試：前端開發(fā)者可直接通過瀏覽器調(diào)試接口，提升協(xié)作效率；
  4. 工程化支撐：基于 Buf 實(shí)現(xiàn)規(guī)范管理，適配團(tuán)隊(duì)協(xié)作場(chǎng)景。

該方案已集成到 GoWind Admin 框架中，開箱即用。如果你的 Kratos 項(xiàng)目也需要高效的 API 文檔解決方案，可直接參考本文實(shí)現(xiàn)，或直接使用 GoWind Admin 框架快速搭建企業(yè)級(jí)中后臺(tái)系統(tǒng)。

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容