golang提供Swagger JSON文档服务的预编译UI插件库go-swagger-ui的使用

go-swagger-ui 使用指南

go-swagger-ui 是一个用于提供 Swagger JSON 文档和 Swagger UI 界面的 Golang 处理器库，通常与 grpc-gateway 编译的 Swagger 文档一起使用。

基本用法

import (
	"github.com/esurdam/go-swagger-ui"
)

// Asset 代表一个 AssetFn - 编译后的 bindata swagger 文件
mux := swaggerui.NewServeMux(Asset, "swagger.json") // 添加 swagger bindata 资源

// /swagger.json 提供 JSON 文档
// /swagger-ui 提供 Swagger UI 界面

自定义根路径

import (
	"github.com/esurdam/go-swagger-ui"
)

// Asset 代表一个 AssetFn - 编译后的 bindata swagger 文件
mux := swaggerui.NewServeMuxWithRoot(Asset, "swagger.json", "/v1/auth") // 添加 swagger bindata 资源

// v1/auth/swagger.json 提供 JSON 文档
// v1/auth/swagger-ui 提供 Swagger UI 界面

更新 UI

swagger 目录包含自动生成的输出：

  1. 将更新的资源添加到 //third_party/swagger-ui
  2. 运行 make build 命令，该命令会将 Swagger 编译到 swagger/bindata.go

完整示例

下面是一个完整的示例，展示如何使用 go-swagger-ui：

package main

import (
	"log"
	"net/http"
	
	"github.com/esurdam/go-swagger-ui"
)

// 假设这是通过 go-bindata 生成的 Asset 函数
// 实际使用时需要替换为真实的 bindata 函数
func Asset(name string) ([]byte, error) {
	return []byte{}, nil
}

func main() {
	// 创建默认路由的 Swagger UI 处理器
	mux := swaggerui.NewServeMux(Asset, "swagger.json")
	
	// 或者创建自定义根路径的处理器
	// mux := swaggerui.NewServeMuxWithRoot(Asset, "swagger.json", "/api/docs")
	
	// 创建 HTTP 服务器
	server := &http.Server{
		Addr:    ":8080",
		Handler: mux,
	}
	
	// 启动服务器
	log.Println("Swagger UI 服务启动，访问 http://localhost:8080/swagger-ui")
	log.Fatal(server.ListenAndServe())
}

注意事项

  1. 使用前需要确保已经通过 go-bindata 或其他工具将 Swagger UI 资源编译为 Go 代码
  2. 需要提供有效的 swagger.json 文件路径或内容
  3. 可以通过自定义根路径来避免与其他路由冲突

这个库提供了一种简单的方式来在 Golang 应用中集成 Swagger UI，方便 API 文档的查看和测试。


更多关于golang提供Swagger JSON文档服务的预编译UI插件库go-swagger-ui的使用的实战教程也可以访问 https://www.itying.com/category-94-b0.html

1 回复

更多关于golang提供Swagger JSON文档服务的预编译UI插件库go-swagger-ui的使用的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


使用go-swagger-ui提供Swagger UI服务

go-swagger-ui是一个Go语言的库，它允许你将Swagger UI作为预编译的资源嵌入到你的Go应用中，无需额外安装或配置Swagger UI服务。

安装

首先安装go-swagger-ui库：

go get github.com/swaggest/swgui

基本使用

下面是一个简单的示例，展示如何使用go-swagger-ui提供Swagger UI界面：

package main

import (
	"log"
	"net/http"

	"github.com/swaggest/swgui/v5emb"
)

func main() {
	// 创建Swagger UI处理器
	swaggerUIHandler := v5emb.New(
		"My API", // 标题
		"/swagger.json", // Swagger JSON文件路径
		"/", // 基础路径
	)

	// 设置路由
	http.Handle("/swagger/", http.StripPrefix("/swagger", swaggerUIHandler))
	
	// 模拟提供一个Swagger JSON文件
	http.HandleFunc("/swagger.json", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		_, _ = w.Write([]byte(`{
			"openapi": "3.0.0",
			"info": {
				"title": "Sample API",
				"version": "1.0.0"
			},
			"paths": {
				"/ping": {
					"get": {
						"responses": {
							"200": {
								"description": "OK",
								"content": {
									"text/plain": {
										"schema": {
											"type": "string"
										}
									}
								}
							}
						}
					}
				}
			}
		}`))
	})

	log.Println("Server started at http://localhost:8080/swagger/")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

与Swag库集成

如果你使用swag库生成Swagger文档，可以这样集成：

package main

import (
	"log"
	"net/http"

	"github.com/swaggest/swgui/v5emb"
	"github.com/swaggo/http-swagger"
)

// @title Sample API
// @version 1.0
// @description This is a sample server.
func main() {
	// 使用http-swagger提供Swagger JSON
	http.Handle("/swagger/", http.StripPrefix("/swagger", v5emb.New(
		"Sample API",
		"/swagger/doc.json",
		"/",
	)))
	
	// 使用http-swagger提供Swagger JSON
	http.Handle("/swagger/doc.json", httpSwagger.Handler(
		httpSwagger.URL("/swagger/doc.json"), // 指向自身的URL
	))

	log.Println("Server started at http://localhost:8080/swagger/")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

高级配置

go-swagger-ui提供了一些配置选项：

handler := v5emb.New(
	"My API",
	"/swagger.json",
	"/api",
	v5emb.WithBasePath("/api"), // 设置基础路径
	v5emb.WithTitle("Custom API Title"), // 自定义标题
	v5emb.WithOAuthClientID("your-client-id"), // OAuth配置
	v5emb.WithPersistAuthorization(true), // 保持授权信息
)

使用自定义主题

你可以自定义Swagger UI的主题：

handler := v5emb.New(
	"My API",
	"/swagger.json",
	"/",
	v5emb.WithTheme("dark"), // 使用暗色主题
	// 或者
	v5emb.WithCustomCSS(`
		.swagger-ui .topbar { background-color: #ff0000; }
	`),
)

在生产环境中的建议

  1. 考虑在生产环境中添加认证中间件，限制对Swagger UI的访问
  2. 可以只在开发环境启用Swagger UI
  3. 使用HTTPS保护API文档
// 添加基本认证中间件
func basicAuth(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		user, pass, ok := r.BasicAuth()
		if !ok || user != "admin" || pass != "secret" {
			w.Header().Set("WWW-Authenticate", `Basic realm="Restricted"`)
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}
		next.ServeHTTP(w, r)
	})
}

// 使用
http.Handle("/swagger/", basicAuth(http.StripPrefix("/swagger", swaggerUIHandler)))

go-swagger-ui是一个轻量级的解决方案，可以方便地将Swagger UI集成到你的Go应用中，特别适合需要自托管API文档的场景。

回到顶部