mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-06-05 12:44:22 +00:00
47ef765c1d
Replaces the hand-rolled API docs UI with industry-standard tooling so
external integrations (Postman, Insomnia, openapi-generator) can
consume the panel API without parsing endpoints.js by hand.
Generator
- frontend/scripts/build-openapi.mjs: walks the existing endpoints.js
(still the single source of truth) and emits an OpenAPI 3.0.3 spec
at frontend/public/openapi.json. Handles Gin :param → {param} path
translation, body / query / path parameter splits, 200 + error
response examples, and Bearer + cookie security schemes
- npm run build now runs gen:api before vite build, so the spec is
always in sync with what's documented
Backend
- web/controller/dist.go exposes ServeOpenAPISpec which streams the
embedded dist/openapi.json with a short Cache-Control. Public
endpoint (no auth) so Postman can fetch it without first logging in
- web/web.go wires GET /panel/api/openapi.json before the auth-gated
/panel/api router
Panel
- ApiDocsPage now renders swagger-ui-react fed by the basePath-aware
openapi.json URL. Dark mode is overridden via CSS targeting the
Swagger UI internals
- CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui
vendor chunk (134 KB gzipped) only loads on this lazy route, not on
every panel page
- vite.config: vendor-swagger manualChunk keeps the new dep out of
the main vendor bundle
For Postman: import http://<panel>/panel/api/openapi.json. Everything
from /login + /panel/api/* shows up with auth, params, and examples.
97 lines
2.8 KiB
Go
97 lines
2.8 KiB
Go
package controller
|
|
|
|
import (
|
|
"bytes"
|
|
"embed"
|
|
htmlpkg "html"
|
|
"net/http"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/gin-gonic/gin"
|
|
|
|
"github.com/mhsanaei/3x-ui/v3/config"
|
|
"github.com/mhsanaei/3x-ui/v3/logger"
|
|
"github.com/mhsanaei/3x-ui/v3/web/session"
|
|
)
|
|
|
|
var distFS embed.FS
|
|
|
|
func SetDistFS(fs embed.FS) {
|
|
distFS = fs
|
|
}
|
|
|
|
var distPageBuildTime = time.Now()
|
|
|
|
// ServeOpenAPISpec returns the generated OpenAPI 3.0 description of the
|
|
// panel API. Postman / Insomnia / openapi-generator consume this URL
|
|
// directly; the in-panel Swagger UI page also fetches it. The spec is
|
|
// produced at frontend build time by scripts/build-openapi.mjs and
|
|
// embedded into the binary via the dist FS.
|
|
func ServeOpenAPISpec(c *gin.Context) {
|
|
body, err := distFS.ReadFile("dist/openapi.json")
|
|
if err != nil {
|
|
c.JSON(http.StatusNotFound, gin.H{"success": false, "msg": "openapi.json not found"})
|
|
return
|
|
}
|
|
c.Header("Cache-Control", "public, max-age=300")
|
|
c.Data(http.StatusOK, "application/json; charset=utf-8", body)
|
|
}
|
|
|
|
func serveDistPage(c *gin.Context, name string) {
|
|
body, err := distFS.ReadFile("dist/" + name)
|
|
if err != nil {
|
|
c.String(http.StatusInternalServerError, "missing embedded page: %s", name)
|
|
return
|
|
}
|
|
|
|
basePath := c.GetString("base_path")
|
|
if basePath == "" {
|
|
basePath = "/"
|
|
}
|
|
|
|
if basePath != "/" {
|
|
body = bytes.ReplaceAll(body, []byte(`src="/assets/`), []byte(`src="`+basePath+`assets/`))
|
|
body = bytes.ReplaceAll(body, []byte(`href="/assets/`), []byte(`href="`+basePath+`assets/`))
|
|
}
|
|
|
|
jsEscape := strings.NewReplacer(
|
|
`\`, `\\`,
|
|
`"`, `\"`,
|
|
"\n", `\n`,
|
|
"\r", `\r`,
|
|
"<", `<`,
|
|
">", `>`,
|
|
"&", `&`,
|
|
)
|
|
escapedBase := jsEscape.Replace(basePath)
|
|
csrfToken, err := session.EnsureCSRFToken(c)
|
|
if err != nil {
|
|
logger.Warning("Unable to mint CSRF token for", name+":", err)
|
|
csrfToken = ""
|
|
}
|
|
csrfMeta := []byte(`<meta name="csrf-token" content="` + htmlpkg.EscapeString(csrfToken) + `">`)
|
|
basePathMeta := []byte(`<meta name="base-path" content="` + htmlpkg.EscapeString(basePath) + `">`)
|
|
|
|
nonceAttr := ""
|
|
if nonce := c.GetString("csp_nonce"); nonce != "" {
|
|
nonceAttr = ` nonce="` + htmlpkg.EscapeString(nonce) + `"`
|
|
}
|
|
script := `<script` + nonceAttr + `>window.X_UI_BASE_PATH="` + escapedBase + `"`
|
|
if name != "login.html" {
|
|
escapedVer := jsEscape.Replace(config.GetVersion())
|
|
script += `;window.X_UI_CUR_VER="` + escapedVer + `"`
|
|
}
|
|
script += `;</script>`
|
|
inject := []byte(script)
|
|
inject = append(inject, csrfMeta...)
|
|
inject = append(inject, basePathMeta...)
|
|
inject = append(inject, []byte(`</head>`)...)
|
|
out := bytes.Replace(body, []byte("</head>"), inject, 1)
|
|
|
|
c.Header("Cache-Control", "no-cache, no-store, must-revalidate")
|
|
c.Header("Pragma", "no-cache")
|
|
c.Header("Expires", "0")
|
|
c.Header("Last-Modified", distPageBuildTime.UTC().Format(http.TimeFormat))
|
|
c.Data(http.StatusOK, "text/html; charset=utf-8", out)
|
|
}
|