mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-06-05 12:44:22 +00:00

History

MHSanaei 47ef765c1d feat(api-docs): expose OpenAPI spec + render Swagger UI in panel 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.		2026-05-24 20:06:36 +02:00
..
public	feat(api-docs): expose OpenAPI spec + render Swagger UI in panel	2026-05-24 20:06:36 +02:00
scripts	feat(api-docs): expose OpenAPI spec + render Swagger UI in panel	2026-05-24 20:06:36 +02:00
src	feat(api-docs): expose OpenAPI spec + render Swagger UI in panel	2026-05-24 20:06:36 +02:00
.gitignore	Vue3 migration (#4198 )	2026-05-09 17:47:35 +02:00
eslint.config.js	Frontend rewrite: React + TypeScript with AntD v6 (#4498 )	2026-05-23 15:21:45 +02:00
index.html	feat(frontend): collapse panel pages into a single React Router SPA	2026-05-24 18:37:09 +02:00
login.html	Frontend rewrite: React + TypeScript with AntD v6 (#4498 )	2026-05-23 15:21:45 +02:00
package-lock.json	feat(api-docs): expose OpenAPI spec + render Swagger UI in panel	2026-05-24 20:06:36 +02:00
package.json	feat(api-docs): expose OpenAPI spec + render Swagger UI in panel	2026-05-24 20:06:36 +02:00
README.md	Frontend rewrite: React + TypeScript with AntD v6 (#4498 )	2026-05-23 15:21:45 +02:00
subpage.html	Frontend rewrite: React + TypeScript with AntD v6 (#4498 )	2026-05-23 15:21:45 +02:00
tsconfig.json	Frontend rewrite: React + TypeScript with AntD v6 (#4498 )	2026-05-23 15:21:45 +02:00
vite.config.js	feat(api-docs): expose OpenAPI spec + render Swagger UI in panel	2026-05-24 20:06:36 +02:00

README.md

3x-ui frontend

React 19 + Ant Design 6 + TypeScript + Vite 8. Multi-page app — one HTML entry per panel route — built into ../web/dist/ and embedded into the Go binary via embed.FS.

Dev

npm install
npm run dev

Vite serves on http://localhost:5173/. API calls and /panel/* routes proxy to the Go panel at http://localhost:2053/, so start the Go panel first (go run main.go) and then Vite.

The proxy auto-rewrites /panel, /panel/settings, /panel/inbounds, /panel/xray to the matching Vite-served HTML in dev mode (see MIGRATED_ROUTES in vite.config.js), so the sidebar's production-style links work without round-tripping through Go.

Production build

npm run build

Outputs to ../web/dist/ (HTML at the root, hashed JS/CSS under assets/). The Go binary embeds this directory at compile time and web/controller/dist.go serves the per-page HTML.

Type check and lint

npm run typecheck
npm run lint

tsc --noEmit against tsconfig.json (strict mode, jsx: "react-jsx", @/* → src/* alias). ESLint 10 with eslint.config.js (flat config) — @eslint/js recommended plus typescript-eslint and eslint-plugin-react-hooks rules.

Layout

frontend/
├── *.html                 # Vite entry HTML, one per panel route
├── tsconfig.json
├── eslint.config.js
├── vite.config.js
└── src/
    ├── entries/           # Per-page bootstrap (createRoot + render)
    ├── pages/             # One folder per route, each with the page
    │   ├── index/         # component + helpers + sub-components
    │   ├── login/
    │   ├── inbounds/
    │   ├── clients/
    │   ├── xray/
    │   ├── nodes/
    │   ├── settings/
    │   ├── api-docs/
    │   └── sub/
    ├── components/        # Cross-page React components
    ├── hooks/             # Reusable hooks (useTheme, useWebSocket, …)
    ├── api/               # Axios setup, CSRF interceptor, WebSocket
    ├── i18n/              # react-i18next init (locales live in web/translation/)
    ├── models/            # Inbound, Outbound, Status, … domain classes
    ├── styles/            # Shared CSS modules (page-cards, …)
    └── utils/             # HttpUtil, ObjectUtil, LanguageManager, …

Adding a new page

Add frontend/<page>.html referencing /src/entries/<page>.tsx.
Add src/entries/<page>.tsx that imports the page component and mounts it with createRoot(...).render(...).
Add the page component under src/pages/<page>/.
Register the entry in rollupOptions.input in vite.config.js.
If the page is reachable from the sidebar at /panel/<route>, add it to MIGRATED_ROUTES so the dev proxy serves the Vite HTML.
Wire the Go controller to serveDistPage(c, "<page>.html").