zhangdeman/gin
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: 接入新版本openapi文档, 页面渲染兼容性待调试

Browse Source
This commit is contained in:
白茶清欢
2026-01-07 23:31:48 +08:00
parent 65802c5e86
commit 2ad85fd950
7 changed files with 192 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
router/define.go
View File

@@ -7,6 +7,8 @@
// Date : 2024-07-20 22:57
package router
import "github.com/getkin/kin-openapi/openapi3"
const (
PrefixFuncName = "RouterPrefix" // 路由前缀函数名称
MiddlewareFuncName = "RouterMiddleware" // 路由中间件函数名称
@@ -46,3 +48,15 @@ type UriParam struct {
const (
FieldNameMeta = "Meta" // 元信息字段
)
// DocConfig 文档配置
type DocConfig struct {
Enable bool `json:"enable" toml:"enable" yaml:"enable" dc:"是否启用文档"`
UiTheme string `json:"ui_theme" toml:"ui_theme" yaml:"ui_theme" dc:"文档主题"`
BaseUri string `json:"base_uri" toml:"base_uri" yaml:"base_uri" dc:"文档基础Uri"`
Flag string `json:"flag" toml:"flag" yaml:"flag" dc:"文档标识"`
ServerList *openapi3.Servers `json:"server_list" toml:"server_list" yaml:"server_list" dc:"服务环境列表"`
Info *openapi3.Info `json:"info" toml:"info" yaml:"info" dc:"基础信息"`
SecuritySchemes *openapi3.SecuritySchemes `json:"security_schemes" toml:"security_schemes" yaml:"security_schemes" dc:"服务安全策略"`
CommonParameter *openapi3.ParametersMap `json:"common_parameter" toml:"common_parameter" yaml:"common_parameter" dc:"基础公共参数"`
}

68
router/doc.go
View File

@@ -8,70 +8,10 @@
package router
import (
"reflect"
apiDoc "git.zhangdeman.cn/zhangdeman/api-doc"
"git.zhangdeman.cn/zhangdeman/api-doc/define"
"git.zhangdeman.cn/zhangdeman/api-doc/openapi"
"github.com/getkin/kin-openapi/openapi3"
)
func NewDoc(info *define.Info, servers []*define.ServerItem) *Doc {
if nil == info {
info = &define.Info{
Description: "",
Title: "",
TermsOfService: "",
Contact: &define.Contact{
Name: "",
Url: "",
Email: "",
},
License: nil,
Version: "",
}
}
if nil == info.Contact {
info.Contact = &define.Contact{
Name: "",
Url: "",
Email: "",
}
}
if nil == info.License {
info.License = &define.License{
Name: "",
Url: "",
}
}
return &Doc{
instance: apiDoc.NewOpenapiDoc(
apiDoc.WithDocDescription(info.Description),
apiDoc.WithDocTitle(info.Title),
apiDoc.WithDocContactEmail(info.Contact.Email),
apiDoc.WithDocContactName(info.Contact.Name),
apiDoc.WithDocLicense(info.License.Name),
apiDoc.WithDocServers(servers),
),
}
}
type Doc struct {
instance *apiDoc.Generate
}
// Add 增加接口文档测试
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 21:55 2025/2/14
func (d *Doc) Add(routePrefix string, paramType reflect.Type, resultType reflect.Type) {
_ = d.instance.AddApiFromInAndOut(routePrefix, paramType, resultType)
}
// Data 文档数据
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 21:59 2025/2/14
func (d *Doc) Data() *define.OpenapiDoc {
return d.instance.Doc()
func NewOpenApiDoc(docFlag string, docOption ...openapi.OptionFunc) *openapi3.T {
return openapi.DocManager.NewOpenApiDoc(docFlag, docOption...)
}

71
router/option.go
View File

@@ -8,9 +8,6 @@
package router
import (
"strings"
apiDocDefine "git.zhangdeman.cn/zhangdeman/api-doc/define"
"git.zhangdeman.cn/zhangdeman/gin/middleware"
"git.zhangdeman.cn/zhangdeman/rate_limit/abstract"
"github.com/gin-gonic/gin"
@@ -20,18 +17,14 @@ type SetServerOptionFunc func(so *serverOption)
// serverOption 获取server实例的选项
type serverOption struct {
swaggerUiTheme string // swagger 主题
swaggerBaseUri string // swagger 基础path
globalMiddlewareList []gin.HandlerFunc // 全局中间件列表
disableSwaggerDoc bool // 禁用swagger文档, 特定环境不想展示文档, 可通过次方式禁用
serverInfo *apiDocDefine.Info // 服务器信息
serverList []*apiDocDefine.ServerItem // 服务器环境列表
enablePprof bool // 启用 pprof
enableCors bool // 启动跨域支持
disableInitRequest bool // 禁用初始化请求
loggerCfg *middleware.AccessConfig // 日志配置
initContextData gin.HandlerFunc // 初始化一些请求数据
rateLimitInstance abstract.IRateLimit // 服务流控实例
docConfig DocConfig // 文档配置
globalMiddlewareList []gin.HandlerFunc // 全局中间件列表
enablePprof bool // 启用 pprof
enableCors bool // 启动跨域支持
disableInitRequest bool // 禁用初始化请求
loggerCfg *middleware.AccessConfig // 日志配置
initContextData gin.HandlerFunc // 初始化一些请求数据
rateLimitInstance abstract.IRateLimit // 服务流控实例
}
// WithRateLimitInstance 设置流控实例, 配置为 nil, 代表禁用
@@ -59,14 +52,13 @@ func WithInitContextData(formatFunc func(ctx *gin.Context)) SetServerOptionFunc
}
}
// WithSwaggerUITheme 设置swaggerUI主题
func WithSwaggerUITheme(uiTheme string) SetServerOptionFunc {
// WithDocConfig 设置文档配置
func WithDocConfig(docConfig *DocConfig) SetServerOptionFunc {
return func(so *serverOption) {
uiTheme = strings.TrimSpace(uiTheme)
if len(uiTheme) == 0 {
if nil == docConfig {
return
}
so.swaggerUiTheme = uiTheme
so.docConfig = *docConfig
}
}
@@ -77,45 +69,6 @@ func WithGlobalMiddlewareList(middlewareList ...gin.HandlerFunc) SetServerOption
}
}
// WithSwaggerBaseUri ...
func WithSwaggerBaseUri(baseUri string) SetServerOptionFunc {
return func(so *serverOption) {
baseUri = strings.TrimSpace(baseUri)
if len(baseUri) == 0 {
return
}
baseUri = "/" + strings.TrimLeft(baseUri, "/")
so.swaggerBaseUri = baseUri
}
}
// WithDisableSwaggerDoc 禁用swagger文档
func WithDisableSwaggerDoc() SetServerOptionFunc {
return func(so *serverOption) {
so.disableSwaggerDoc = true
}
}
// WithServerInfo 设置serverInfo
func WithServerInfo(serverInfo *apiDocDefine.Info) SetServerOptionFunc {
return func(so *serverOption) {
if nil == serverInfo {
return
}
so.serverInfo = serverInfo
}
}
// WithServerList 设置服务器列表
func WithServerList(serverList []*apiDocDefine.ServerItem) SetServerOptionFunc {
return func(so *serverOption) {
if len(serverList) == 0 {
return
}
so.serverList = serverList
}
}
// WithPprofEnable 启用pprof
func WithPprofEnable() SetServerOptionFunc {
return func(so *serverOption) {

104
router/server.go
View File

@@ -16,19 +16,19 @@ import (
"strings"
"sync"
apiDoc "git.zhangdeman.cn/zhangdeman/api-doc"
apiDocDefine "git.zhangdeman.cn/zhangdeman/api-doc/define"
"git.zhangdeman.cn/zhangdeman/api-doc/enums"
"git.zhangdeman.cn/zhangdeman/api-doc/openapi"
"git.zhangdeman.cn/zhangdeman/gin/define"
"git.zhangdeman.cn/zhangdeman/graceful"
"github.com/jedib0t/go-pretty/v6/table"
"github.com/jedib0t/go-pretty/v6/text"
apiDoc "git.zhangdeman.cn/zhangdeman/api-doc"
"git.zhangdeman.cn/zhangdeman/consts"
"git.zhangdeman.cn/zhangdeman/gin/middleware"
"git.zhangdeman.cn/zhangdeman/gin/middleware/request_cors"
"github.com/gin-contrib/pprof"
apiDocDefine "git.zhangdeman.cn/zhangdeman/api-doc/define"
apiDocEnum "git.zhangdeman.cn/zhangdeman/api-doc/enums"
"github.com/gin-gonic/gin"
)
@@ -39,32 +39,7 @@ func NewServerOption(port int, optionList ...SetServerOptionFunc) *serverOption
func newServerOption(port int, optionList ...SetServerOptionFunc) *serverOption {
option := &serverOption{
swaggerUiTheme: apiDocEnum.SwaggerUIThemeRedocFree.String(),
swaggerBaseUri: "/doc/swagger",
globalMiddlewareList: nil,
disableSwaggerDoc: false,
serverInfo: &apiDocDefine.Info{
Description: "这是一个微服务，提供一些必要的的数据接口功能",
Title: "微服务接口文档",
TermsOfService: "",
Contact: &apiDocDefine.Contact{
Name: "开发人员",
Url: "",
Email: "developer@example.com",
},
License: &apiDocDefine.License{
Name: consts.LicenseApache20,
Url: consts.LicenseUrlTable[consts.LicenseApache20],
},
Version: "0.0.1",
},
serverList: []*apiDocDefine.ServerItem{
{
Url: fmt.Sprintf("http://127.0.0.1:%d", port),
Description: "测试服务器",
Variables: nil,
},
},
}
for _, opt := range optionList {
if nil == opt {
@@ -83,9 +58,28 @@ func NewServer(port int, optionList ...SetServerOptionFunc) *server {
gin.SetMode(gin.ReleaseMode)
option := newServerOption(port, optionList...)
// 启用文档, 初始化文档
if option.docConfig.Enable {
if len(option.docConfig.BaseUri) == 0 {
option.docConfig.BaseUri = "/_doc/swagger" // 未指定文档基础路径, 则以默认值作为基础路径
}
if len(option.docConfig.Flag) == 0 {
option.docConfig.Flag = fmt.Sprintf("%v", port) // 未指定文档实例标识, 则以监听端口作为实例
}
// base_uri 拼接 文档标识, 作为最终 baseUri
option.docConfig.BaseUri = fmt.Sprintf("%v/%v", strings.TrimRight(option.docConfig.BaseUri, "/"), strings.Trim(option.docConfig.Flag, "/"))
optionFuncList := []openapi.OptionFunc{
openapi.WithInfo(option.docConfig.Info),
openapi.WithSecurity(option.docConfig.SecuritySchemes),
openapi.WithCommonParameter(option.docConfig.CommonParameter),
}
if nil != option.docConfig.ServerList {
optionFuncList = append(optionFuncList, openapi.WithServers(*option.docConfig.ServerList))
}
openapi.DocManager.NewOpenApiDoc(option.docConfig.Flag, optionFuncList...)
}
s := &server{
router: gin.Default(),
uiInstance: apiDoc.NewSwaggerUI(option.serverInfo, option.serverList, apiDocEnum.SwaggerUITheme(option.swaggerUiTheme)),
port: port,
option: option,
lock: &sync.RWMutex{},
@@ -108,7 +102,6 @@ func NewServer(port int, optionList ...SetServerOptionFunc) *server {
type server struct {
router *gin.Engine
port int
uiInstance *apiDoc.SwaggerUI
option *serverOption
commonParam map[string]GetCommonParam // 结构体字段名, 注意, 不是TAG
lock *sync.RWMutex
@@ -157,10 +150,48 @@ func (s *server) getGlobalMiddlewareList(option *serverOption) {
s.globalMiddlewareDescList = s.getMiddlewareDescList(s.globalMiddlewareList)
}
// RegisterDocHandler 注册文档路由
func (s *server) RegisterDocHandler() {
if !s.option.docConfig.Enable {
return
}
s.router.GET(s.option.docConfig.BaseUri+"/*any", func(ctx *gin.Context) {
if ctx.Request.RequestURI == s.option.docConfig.BaseUri+"/doc.json" || ctx.Request.RequestURI == s.option.docConfig.BaseUri+"/knife4go/doc.json" {
// 默认swagger, 通过此接口读取文档数据
ctx.JSON(http.StatusOK, openapi.DocManager.DocData(s.option.docConfig.Flag))
ctx.Abort()
}
if ctx.Request.RequestURI == "/doc/swagger/openapi.json" {
// knife4go 文档通过此接口读取文档列表
ctx.JSON(http.StatusOK, []map[string]any{
{
"name": "服务文档",
"url": "doc.json",
"swaggerVersion": enums.SwaggerDocVersion3.String(),
},
})
ctx.Abort()
}
}, apiDoc.NewSwaggerUI(fmt.Sprintf("[%v]接口文档", s.option.docConfig.Flag), s.option.docConfig.BaseUri, enums.SwaggerUITheme(s.option.docConfig.UiTheme)).Handler())
s.router.GET("/swagger-resources", func(ctx *gin.Context) { // lucky UI获取分组信息
ctx.Writer.Header().Set("Access-Control-Allow-Origin", "*") // 允许访问所有域
ctx.JSON(http.StatusOK, []map[string]any{
{
"name": "服务文档",
"url": s.option.docConfig.BaseUri + "/doc.json",
"swaggerVersion": enums.SwaggerDocVersion3.String(),
},
})
// ctx.JSON(http.StatusOK, swaggerInstance.docInstance.Data())
})
}
// Start 启动服务
func (s *server) Start() {
// 注册文档
s.uiInstance.RegisterHandler(s.router, s.option.swaggerBaseUri)
s.RegisterDocHandler()
// s.uiInstance.RegisterHandler(s.router, s.option.swaggerBaseUri)
gracefulServer := graceful.NewServer(fmt.Sprintf(":%d", s.port), s.Router())
defer func() {
_ = gracefulServer.Close()
@@ -215,7 +246,7 @@ func (s *server) Group(routerPrefix string, middlewareList []gin.HandlerFunc, co
// 设置 logic 函数描述
apiMiddlewareList = append(apiMiddlewareList, runtime.FuncForPC(itemUriCfg.ApiLogicFunc.Func.Pointer()).Name())
_ = s.uiInstance.DocInstance().AddApiFromInAndOut(routerPrefix, itemUriCfg.FormDataType, itemUriCfg.ResultDataType)
// _ = s.uiInstance.DocInstance().AddApiFromInAndOut(routerPrefix, itemUriCfg.FormDataType, itemUriCfg.ResultDataType)
// 普通 HTTP 请求
handleFunc := s.RequestHandler(itemUriCfg)
if itemUriCfg.IsSse {
@@ -228,6 +259,13 @@ func (s *server) Group(routerPrefix string, middlewareList []gin.HandlerFunc, co
routerPrefix = "/" + strings.TrimSuffix(strings.TrimPrefix(routerPrefix, "/"), "/")
}
fullUriPath := routerPrefix + "/" + strings.TrimPrefix(itemUriCfg.Path, "/")
// 注册接口文档
_ = openapi.DocManager.AddApiDoc(s.option.docConfig.Flag, apiDocDefine.UriConfig{
Path: fullUriPath,
RequestMethod: method,
TagList: itemUriCfg.TagList,
Desc: itemUriCfg.Desc,
}, itemUriCfg.FormDataType, itemUriCfg.ResultDataType)
s.uriTable[fullUriPath] = itemUriCfg // 注册路由时存储 接口路径 => 接口配置的信息
s.consoleOutput = append(s.consoleOutput, []any{
fullUriPath,

13
router/server_test.go
View File

@@ -19,13 +19,22 @@ type testCommon struct {
}
type testForm struct {
Meta `json:"-" method:"get" path:"test" rate-limit:"1/5/60"`
Meta `json:"-" method:"get" path:"test" rate-limit:"1/5/60" tag:"测试,验证" summary:"本地调试"`
testCommon
Name string `json:"name"`
}
func TestNewServer(t *testing.T) {
s := NewServer(9087, WithRateLimitInstance(rate_limit.MemoryClient))
s := NewServer(9087, WithRateLimitInstance(rate_limit.MemoryClient), WithDocConfig(&DocConfig{
Enable: true,
UiTheme: "ydoc-lucky-ui",
BaseUri: "",
Flag: "test-server",
ServerList: nil,
Info: nil,
SecuritySchemes: nil,
CommonParameter: nil,
}))
s.AddCommonParamRule("UserID", func(ctx *gin.Context) (any, error) {
return uint(123456), nil
})