go get github.com/LingByte/ling-base/apidocs

package main

import (
    "context"
    "net/http"

    "github.com/LingByte/ling-base/apidocs"
    "github.com/danielgtaylor/huma/v2"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.New()
    api := apidocs.Mount(r, apidocs.Options{
        Title:   "My API",
        Version: "1.0.0",
    })

    type helloOutput struct {
        Body struct {
            Msg string `json:"msg"`
        }
    }
    huma.Register(api, huma.Operation{
        OperationID: "hello",
        Method:      http.MethodGet,
        Path:        "/hello",
        Summary:     "打招呼",
    }, func(ctx context.Context, _ *struct{}) (*helloOutput, error) {
        return &helloOutput{Body: struct {
            Msg string `json:"msg"`
        }{Msg: "hello"}}, nil
    })

    r.Run(":8080")
    // 访问 http://localhost:8080/docs
}

apidocs.Mount(r, apidocs.Options{Theme: apidocs.ThemeScalar})    // 默认，现代风格
apidocs.Mount(r, apidocs.Options{Theme: apidocs.ThemeSwagger})   // 经典风格
apidocs.Mount(r, apidocs.Options{Theme: apidocs.ThemeRedoc})     // 三栏布局
apidocs.Mount(r, apidocs.Options{Theme: apidocs.ThemeStoplight}) // 设计优先

apidocs.Mount(r, apidocs.Options{
    CDN: apidocs.CDNConfig{Mode: apidocs.CDNModePublic},
})

apidocs.Mount(r, apidocs.Options{
    CDN: apidocs.CDNConfig{
        Mode:    apidocs.CDNModeSelfHosted,
        BaseURL: "https://assets.internal.company.com/openapi-ui",
    },
})

apidocs.Mount(r, apidocs.Options{
    CDN: apidocs.CDNConfig{
        Mode:     apidocs.CDNModeCustom,
        ScalarJS: "https://cdn.mycompany.com/scalar.js",
        SwaggerJS: "https://cdn.mycompany.com/swagger.js",
    },
})

apidocs.Mount(r, apidocs.Options{
    Title:    "My API",
    Version:  "1.0.0",
    DarkMode: true,
    CSS:      ".topbar { background: #1a1a2e; }",
    Logo:     logoPNG,               // []byte
    LogoContentType: "image/png",
    CustomJS: "console.log('docs loaded');",
    CustomHeadHTML: `<meta name="author" content="MyCorp">`,
})

apidocs.Mount(r, apidocs.Options{
    Title: "My API",
    TopBar: apidocs.TopBarConfig{
        Subtitle:    "API Reference",           // 默认 "接口文档"
        EnvLabel:    "STAGING",                 // 环境标识
        EnvLabelColor: "#ef4444",               // 红色
        ExtraButtons: `<a href="/">返回首页</a>`,
        // HideTopBar:       true,              // 完全隐藏 topbar
        // CustomHTML:       "<header>...</header>", // 完全自定义
        // ShowExportButtons: &f,               // false 隐藏导出按钮
    },
})

// 用环境变量控制
apidocs.Mount(r, apidocs.Options{
    Title: "My API",
    EnabledFunc: func() bool {
        return os.Getenv("APP_ENV") != "prod"
    },
})

// 用 config 模块控制
apidocs.Mount(r, apidocs.Options{
    EnabledFunc: func() bool { return cfg.Env != "prod" },
})

// 生产环境关闭文档 UI，但保留 OpenAPI spec 给工具用
tr := true
apidocs.Mount(r, apidocs.Options{
    EnabledFunc: func() bool { return os.Getenv("APP_ENV") != "prod" },
    ExposeSpec:  &tr,
})

apidocs.Mount(r, apidocs.Options{
    SecuritySchemes: map[string]apidocs.SecurityScheme{
        "BearerAuth": {
            Type:         "http",
            Scheme:       "bearer",
            BearerFormat: "JWT",
        },
    },
    GlobalSecurity: []map[string][]string{
        {"BearerAuth": {}},
    },
})

SecuritySchemes: map[string]apidocs.SecurityScheme{
    "ApiKey": {Type: "apiKey", In: "header", Name: "X-API-Key"},
}

SecuritySchemes: map[string]apidocs.SecurityScheme{
    "OAuth2": {
        Type: "oauth2",
        Flows: &huma.OAuthFlows{
            AuthorizationCode: &huma.OAuthFlow{
                AuthorizationURL: "https://example.com/oauth/authorize",
                TokenURL:         "https://example.com/oauth/token",
                Scopes: map[string]string{
                    "read":  "read access",
                    "write": "write access",
                },
            },
        },
    },
}

apidocs.Mount(r, apidocs.Options{
    Title:          "My API",
    Version:        "1.0.0",
    Description:    "## My API\n\n支持 **Markdown**。",
    TermsOfService: "https://example.com/terms",
    Contact: &huma.Contact{
        Name:  "API Support",
        Email: "support@example.com",
        URL:   "https://example.com/support",
    },
    License: &huma.License{
        Name: "MIT",
        URL:  "https://opensource.org/licenses/MIT",
    },
    ExternalDocs: &huma.ExternalDocs{
        URL:         "https://example.com/docs",
        Description: "更多文档",
    },
})

apidocs.Mount(r, apidocs.Options{
    Theme: apidocs.ThemeScalar,
    ScalarConfig: map[string]any{
        "hideModels":  true,
        "layout":      "classic",
    },
})

apidocs.Mount(r, apidocs.Options{
    Theme: apidocs.ThemeSwagger,
    SwaggerConfig: map[string]any{
        "docExpansion": "none",
        "filter":       true,
    },
})