mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-06-05 12:44:22 +00:00
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.
This commit is contained in:
MHSanaei
parent
77099f91e8
commit
47ef765c1d
15 changed files with 7227 additions and 1038 deletions
1987
frontend/package-lock.json
generated
1987
frontend/package-lock.json
generated
File diff suppressed because it is too large
Load diff
|
|
@ -10,10 +10,11 @@
|
|||
},
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "vite build",
|
||||
"build": "npm run gen:api && vite build",
|
||||
"preview": "vite preview",
|
||||
"lint": "eslint src",
|
||||
"typecheck": "tsc --noEmit"
|
||||
"typecheck": "tsc --noEmit",
|
||||
"gen:api": "node scripts/build-openapi.mjs"
|
||||
},
|
||||
"dependencies": {
|
||||
"@ant-design/icons": "^6.2.3",
|
||||
|
|
@ -32,12 +33,14 @@
|
|||
"react": "^19.2.6",
|
||||
"react-dom": "^19.2.6",
|
||||
"react-i18next": "^17.0.8",
|
||||
"react-router-dom": "^7.15.1"
|
||||
"react-router-dom": "^7.15.1",
|
||||
"swagger-ui-react": "^5.32.6"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint/js": "^10.0.1",
|
||||
"@types/react": "^19.2.15",
|
||||
"@types/react-dom": "^19.2.3",
|
||||
"@types/swagger-ui-react": "^5.18.0",
|
||||
"@vitejs/plugin-react": "^6.0.2",
|
||||
"eslint": "^10.4.0",
|
||||
"eslint-plugin-react-hooks": "^7.1.1",
|
||||
|
|
|
|||
4944
frontend/public/openapi.json
Normal file
4944
frontend/public/openapi.json
Normal file
File diff suppressed because it is too large
Load diff
218
frontend/scripts/build-openapi.mjs
Normal file
218
frontend/scripts/build-openapi.mjs
Normal file
|
|
@ -0,0 +1,218 @@
|
|||
#!/usr/bin/env node
|
||||
import { writeFileSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
|
||||
import { sections } from '../src/pages/api-docs/endpoints.js';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const outPath = join(__dirname, '..', 'public', 'openapi.json');
|
||||
|
||||
const PANEL_VERSION = process.env.X_UI_VERSION || '3.x';
|
||||
|
||||
const SECURITY_SCHEMES = {
|
||||
bearerAuth: {
|
||||
type: 'http',
|
||||
scheme: 'bearer',
|
||||
description: 'API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.',
|
||||
},
|
||||
cookieAuth: {
|
||||
type: 'apiKey',
|
||||
in: 'cookie',
|
||||
name: '3x-ui',
|
||||
description: 'Session cookie set by POST /login. Browser-only.',
|
||||
},
|
||||
};
|
||||
|
||||
function ginPathToOpenApi(path) {
|
||||
return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, '{$1}');
|
||||
}
|
||||
|
||||
function extractPathParams(openApiPath) {
|
||||
const params = [];
|
||||
const re = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
|
||||
let m;
|
||||
while ((m = re.exec(openApiPath)) !== null) params.push(m[1]);
|
||||
return params;
|
||||
}
|
||||
|
||||
function mapType(t) {
|
||||
const v = String(t || '').toLowerCase();
|
||||
if (v === 'number' || v === 'integer' || v === 'int') return 'integer';
|
||||
if (v === 'float' || v === 'double') return 'number';
|
||||
if (v === 'boolean' || v === 'bool') return 'boolean';
|
||||
if (v === 'array') return 'array';
|
||||
if (v === 'object') return 'object';
|
||||
return 'string';
|
||||
}
|
||||
|
||||
function tryParseJson(raw) {
|
||||
if (typeof raw !== 'string') return undefined;
|
||||
try {
|
||||
return JSON.parse(raw);
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function paramToOpenApi(p) {
|
||||
const out = {
|
||||
name: p.name,
|
||||
in: p.in,
|
||||
required: p.in === 'path' ? true : !p.optional,
|
||||
description: p.desc || '',
|
||||
schema: { type: mapType(p.type) },
|
||||
};
|
||||
if (p.defaultValue !== undefined) out.schema.default = p.defaultValue;
|
||||
return out;
|
||||
}
|
||||
|
||||
function buildOperation(ep, tag) {
|
||||
const op = {
|
||||
tags: [tag],
|
||||
summary: ep.summary || '',
|
||||
operationId: `${ep.method.toLowerCase()}_${ep.path.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_|_$/g, '')}`,
|
||||
};
|
||||
if (ep.description) op.description = ep.description;
|
||||
if (ep.deprecated) op.deprecated = true;
|
||||
|
||||
const params = [];
|
||||
const bodyParams = [];
|
||||
for (const p of ep.params || []) {
|
||||
if (p.in === 'body') {
|
||||
bodyParams.push(p);
|
||||
} else if (p.in === 'path' || p.in === 'query' || p.in === 'header') {
|
||||
params.push(paramToOpenApi(p));
|
||||
}
|
||||
}
|
||||
|
||||
const openApiPath = ginPathToOpenApi(ep.path);
|
||||
const declared = new Set(params.filter((x) => x.in === 'path').map((x) => x.name));
|
||||
for (const name of extractPathParams(openApiPath)) {
|
||||
if (declared.has(name)) continue;
|
||||
params.push({
|
||||
name,
|
||||
in: 'path',
|
||||
required: true,
|
||||
description: '',
|
||||
schema: { type: 'string' },
|
||||
});
|
||||
}
|
||||
|
||||
if (params.length > 0) op.parameters = params;
|
||||
|
||||
if (ep.body || bodyParams.length > 0) {
|
||||
const example = tryParseJson(ep.body);
|
||||
const properties = {};
|
||||
const required = [];
|
||||
for (const bp of bodyParams) {
|
||||
properties[bp.name] = {
|
||||
type: mapType(bp.type),
|
||||
description: bp.desc || '',
|
||||
};
|
||||
if (!bp.optional) required.push(bp.name);
|
||||
}
|
||||
const schema = bodyParams.length > 0
|
||||
? { type: 'object', properties, ...(required.length > 0 ? { required } : {}) }
|
||||
: { type: 'object' };
|
||||
|
||||
op.requestBody = {
|
||||
required: required.length > 0 || bodyParams.length === 0,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema,
|
||||
...(example !== undefined ? { example } : {}),
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const responses = {};
|
||||
const successExample = tryParseJson(ep.response);
|
||||
responses['200'] = {
|
||||
description: 'Successful response',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean' },
|
||||
msg: { type: 'string' },
|
||||
obj: {},
|
||||
},
|
||||
},
|
||||
...(successExample !== undefined ? { example: successExample } : {}),
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
const errExample = tryParseJson(ep.errorResponse);
|
||||
if (errExample !== undefined || ep.errorStatus) {
|
||||
const code = String(ep.errorStatus || 400);
|
||||
responses[code] = {
|
||||
description: 'Error response',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean' },
|
||||
msg: { type: 'string' },
|
||||
},
|
||||
},
|
||||
...(errExample !== undefined ? { example: errExample } : {}),
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
op.responses = responses;
|
||||
return op;
|
||||
}
|
||||
|
||||
function buildSpec() {
|
||||
const paths = {};
|
||||
for (const section of sections) {
|
||||
const tag = section.title;
|
||||
for (const ep of section.endpoints) {
|
||||
const openApiPath = ginPathToOpenApi(ep.path);
|
||||
if (!paths[openApiPath]) paths[openApiPath] = {};
|
||||
paths[openApiPath][ep.method.toLowerCase()] = buildOperation(ep, tag);
|
||||
}
|
||||
}
|
||||
|
||||
const tags = sections.map((s) => ({
|
||||
name: s.title,
|
||||
description: s.description || '',
|
||||
}));
|
||||
|
||||
return {
|
||||
openapi: '3.0.3',
|
||||
info: {
|
||||
title: '3X-UI Panel API',
|
||||
version: PANEL_VERSION,
|
||||
description:
|
||||
'Programmatic interface to a 3X-UI panel. Authenticate either by logging in (cookie) or with an API token from Settings → Security → API Token (Bearer). All endpoints under /panel/api/* honour both modes.',
|
||||
},
|
||||
servers: [
|
||||
{ url: '/', description: 'Current panel (basePath aware)' },
|
||||
],
|
||||
components: {
|
||||
securitySchemes: SECURITY_SCHEMES,
|
||||
},
|
||||
security: [{ bearerAuth: [] }, { cookieAuth: [] }],
|
||||
tags,
|
||||
paths,
|
||||
};
|
||||
}
|
||||
|
||||
const spec = buildSpec();
|
||||
writeFileSync(outPath, JSON.stringify(spec, null, 2) + '\n');
|
||||
|
||||
const pathCount = Object.keys(spec.paths).length;
|
||||
let opCount = 0;
|
||||
for (const ops of Object.values(spec.paths)) opCount += Object.keys(ops).length;
|
||||
console.log(`[openapi] wrote ${outPath}`);
|
||||
console.log(`[openapi] paths: ${pathCount}, operations: ${opCount}, tags: ${spec.tags.length}`);
|
||||
|
||||
void pathToFileURL;
|
||||
|
|
@ -20,273 +20,81 @@
|
|||
}
|
||||
|
||||
.api-docs-page .content-area {
|
||||
padding: 24px;
|
||||
padding: 16px;
|
||||
max-width: 100%;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.api-docs-page .content-area {
|
||||
padding: 16px 12px 12px;
|
||||
padding-top: 64px;
|
||||
padding: 8px;
|
||||
padding-top: 56px;
|
||||
}
|
||||
}
|
||||
|
||||
.docs-wrapper {
|
||||
max-width: 1100px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
.docs-header {
|
||||
margin-bottom: 20px;
|
||||
padding: 24px;
|
||||
.api-docs-page .docs-wrapper {
|
||||
background: var(--bg-card);
|
||||
border: 1px solid rgba(128, 128, 128, 0.12);
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
.docs-title {
|
||||
font-size: 28px;
|
||||
font-weight: 800;
|
||||
margin: 0 0 8px;
|
||||
color: rgba(0, 0, 0, 0.88);
|
||||
letter-spacing: -0.3px;
|
||||
}
|
||||
|
||||
.docs-lead {
|
||||
margin: 0;
|
||||
color: rgba(0, 0, 0, 0.65);
|
||||
line-height: 1.65;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.docs-lead code,
|
||||
.token-hint code {
|
||||
background: rgba(128, 128, 128, 0.12);
|
||||
padding: 1px 6px;
|
||||
border-radius: 4px;
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 12.5px;
|
||||
}
|
||||
|
||||
.token-card,
|
||||
.curl-card {
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.token-card-head {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 12px;
|
||||
flex-wrap: wrap;
|
||||
margin-bottom: 10px;
|
||||
min-height: 32px;
|
||||
}
|
||||
|
||||
.token-card-title {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-weight: 600;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.token-hint {
|
||||
margin: 10px 0 0;
|
||||
color: rgba(0, 0, 0, 0.55);
|
||||
font-size: 12.5px;
|
||||
line-height: 1.55;
|
||||
}
|
||||
|
||||
.toolbar {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
flex-wrap: wrap;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.search-bar {
|
||||
flex: 1;
|
||||
min-width: 200px;
|
||||
max-width: 480px;
|
||||
}
|
||||
|
||||
.match-count {
|
||||
font-size: 12px;
|
||||
color: rgba(0, 0, 0, 0.5);
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.toc-nav {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: flex-start;
|
||||
gap: 8px 12px;
|
||||
padding: 12px 16px;
|
||||
background: var(--bg-card);
|
||||
border: 1px solid rgba(128, 128, 128, 0.12);
|
||||
border-radius: 8px;
|
||||
margin-bottom: 16px;
|
||||
border: 1px solid rgba(128, 128, 128, 0.12);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.toc-label {
|
||||
font-size: 11px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.6px;
|
||||
color: rgba(0, 0, 0, 0.5);
|
||||
padding-top: 3px;
|
||||
flex-shrink: 0;
|
||||
.api-docs-page .swagger-ui {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
|
||||
}
|
||||
|
||||
.toc-links {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 6px;
|
||||
.api-docs-page.is-dark .swagger-ui,
|
||||
.api-docs-page.is-dark .swagger-ui .info .title,
|
||||
.api-docs-page.is-dark .swagger-ui .info p,
|
||||
.api-docs-page.is-dark .swagger-ui .opblock-tag,
|
||||
.api-docs-page.is-dark .swagger-ui .opblock .opblock-summary-path,
|
||||
.api-docs-page.is-dark .swagger-ui .opblock .opblock-summary-description,
|
||||
.api-docs-page.is-dark .swagger-ui table thead tr td,
|
||||
.api-docs-page.is-dark .swagger-ui table thead tr th,
|
||||
.api-docs-page.is-dark .swagger-ui .parameter__name,
|
||||
.api-docs-page.is-dark .swagger-ui .parameter__type,
|
||||
.api-docs-page.is-dark .swagger-ui .response-col_status,
|
||||
.api-docs-page.is-dark .swagger-ui .response-col_description,
|
||||
.api-docs-page.is-dark .swagger-ui label,
|
||||
.api-docs-page.is-dark .swagger-ui .tab li,
|
||||
.api-docs-page.is-dark .swagger-ui .markdown p,
|
||||
.api-docs-page.is-dark .swagger-ui .markdown li {
|
||||
color: rgba(255, 255, 255, 0.85);
|
||||
}
|
||||
|
||||
.toc-link {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 5px;
|
||||
padding: 4px 10px;
|
||||
border-radius: 20px;
|
||||
font-size: 12.5px;
|
||||
color: rgba(0, 0, 0, 0.65);
|
||||
background: rgba(128, 128, 128, 0.06);
|
||||
border: 1px solid transparent;
|
||||
text-decoration: none;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.toc-link:hover {
|
||||
background: rgba(22, 119, 255, 0.08);
|
||||
color: #1677ff;
|
||||
border-color: rgba(22, 119, 255, 0.2);
|
||||
}
|
||||
|
||||
.toc-link.active {
|
||||
background: rgba(22, 119, 255, 0.12);
|
||||
color: #1677ff;
|
||||
border-color: rgba(22, 119, 255, 0.3);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.toc-icon {
|
||||
font-size: 13px;
|
||||
opacity: 0.8;
|
||||
}
|
||||
|
||||
.toc-text {
|
||||
font-size: 12.5px;
|
||||
}
|
||||
|
||||
.toc-badge {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
min-width: 18px;
|
||||
height: 18px;
|
||||
padding: 0 5px;
|
||||
border-radius: 9px;
|
||||
font-size: 10.5px;
|
||||
font-weight: 700;
|
||||
background: rgba(22, 119, 255, 0.12);
|
||||
color: #1677ff;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
.toc-link.active .toc-badge {
|
||||
background: #1677ff;
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
body.dark .docs-title {
|
||||
color: rgba(255, 255, 255, 0.92);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .docs-title {
|
||||
color: rgba(255, 255, 255, 0.95);
|
||||
}
|
||||
|
||||
body.dark .docs-header {
|
||||
background: #252526;
|
||||
.api-docs-page.is-dark .swagger-ui .opblock {
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
border-color: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .docs-header {
|
||||
background: #0a0a0a;
|
||||
border-color: rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
||||
body.dark .docs-lead,
|
||||
body.dark .token-hint {
|
||||
color: rgba(255, 255, 255, 0.7);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .docs-lead,
|
||||
html[data-theme='ultra-dark'] .token-hint {
|
||||
color: rgba(255, 255, 255, 0.75);
|
||||
}
|
||||
|
||||
body.dark .docs-lead code,
|
||||
body.dark .token-hint code {
|
||||
background: rgba(255, 255, 255, 0.1);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .docs-lead code,
|
||||
html[data-theme='ultra-dark'] .token-hint code {
|
||||
background: rgba(255, 255, 255, 0.12);
|
||||
}
|
||||
|
||||
body.dark .toc-nav {
|
||||
background: #252526;
|
||||
border-color: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .toc-nav {
|
||||
background: #0a0a0a;
|
||||
border-color: rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
||||
body.dark .toc-label {
|
||||
color: rgba(255, 255, 255, 0.55);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .toc-label {
|
||||
color: rgba(255, 255, 255, 0.6);
|
||||
}
|
||||
|
||||
body.dark .toc-link {
|
||||
color: rgba(255, 255, 255, 0.65);
|
||||
background: rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .toc-link {
|
||||
.api-docs-page.is-dark .swagger-ui .opblock .opblock-section-header {
|
||||
background: rgba(255, 255, 255, 0.04);
|
||||
box-shadow: none;
|
||||
}
|
||||
|
||||
body.dark .toc-link:hover {
|
||||
background: rgba(88, 166, 255, 0.12);
|
||||
color: #58a6ff;
|
||||
border-color: rgba(88, 166, 255, 0.25);
|
||||
.api-docs-page.is-dark .swagger-ui input[type=text],
|
||||
.api-docs-page.is-dark .swagger-ui textarea,
|
||||
.api-docs-page.is-dark .swagger-ui select {
|
||||
background: rgba(0, 0, 0, 0.3);
|
||||
color: rgba(255, 255, 255, 0.9);
|
||||
border-color: rgba(255, 255, 255, 0.15);
|
||||
}
|
||||
|
||||
body.dark .toc-link.active {
|
||||
background: rgba(88, 166, 255, 0.15);
|
||||
color: #58a6ff;
|
||||
border-color: rgba(88, 166, 255, 0.35);
|
||||
.api-docs-page.is-dark .swagger-ui .scheme-container {
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
box-shadow: none;
|
||||
}
|
||||
|
||||
body.dark .toc-badge {
|
||||
background: rgba(88, 166, 255, 0.15);
|
||||
color: #58a6ff;
|
||||
.api-docs-page.is-dark .swagger-ui .model-box,
|
||||
.api-docs-page.is-dark .swagger-ui section.models {
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
border-color: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
body.dark .toc-link.active .toc-badge {
|
||||
background: #58a6ff;
|
||||
color: #0d1117;
|
||||
.api-docs-page.is-dark .swagger-ui section.models .model-container {
|
||||
background: rgba(255, 255, 255, 0.02);
|
||||
}
|
||||
|
||||
.api-docs-page.is-dark .swagger-ui .highlight-code,
|
||||
.api-docs-page.is-dark .swagger-ui .microlight {
|
||||
background: #0d0d10;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,142 +1,19 @@
|
|||
import { useCallback, useEffect, useMemo, useState } from 'react';
|
||||
import type { ComponentType, MouseEvent } from 'react';
|
||||
import { Button, Card, ConfigProvider, Input, Layout, Space } from 'antd';
|
||||
import {
|
||||
ApiOutlined,
|
||||
CloudServerOutlined,
|
||||
ClusterOutlined,
|
||||
CompressOutlined,
|
||||
ExpandOutlined,
|
||||
GlobalOutlined,
|
||||
KeyOutlined,
|
||||
LinkOutlined,
|
||||
NodeIndexOutlined,
|
||||
SafetyCertificateOutlined,
|
||||
SaveOutlined,
|
||||
SearchOutlined,
|
||||
SettingOutlined,
|
||||
WifiOutlined,
|
||||
} from '@ant-design/icons';
|
||||
import { useMemo } from 'react';
|
||||
import { ConfigProvider, Layout } from 'antd';
|
||||
import SwaggerUI from 'swagger-ui-react';
|
||||
import 'swagger-ui-react/swagger-ui.css';
|
||||
|
||||
import { useTheme } from '@/hooks/useTheme';
|
||||
import AppSidebar from '@/components/AppSidebar';
|
||||
import { sections as allSections } from './endpoints.js';
|
||||
import EndpointSection from './EndpointSection';
|
||||
import type { Section } from './EndpointSection';
|
||||
import CodeBlock from './CodeBlock';
|
||||
import '@/styles/page-cards.css';
|
||||
import './ApiDocsPage.css';
|
||||
|
||||
const sectionIcons: Record<string, ComponentType<{ className?: string }>> = {
|
||||
authentication: SafetyCertificateOutlined,
|
||||
inbounds: NodeIndexOutlined,
|
||||
server: CloudServerOutlined,
|
||||
nodes: ClusterOutlined,
|
||||
'custom-geo': GlobalOutlined,
|
||||
backup: SaveOutlined,
|
||||
settings: SettingOutlined,
|
||||
'api-tokens': KeyOutlined,
|
||||
'xray-settings': WifiOutlined,
|
||||
subscription: LinkOutlined,
|
||||
websocket: ApiOutlined,
|
||||
};
|
||||
|
||||
const curlExample = `curl -X GET \\
|
||||
-H "Authorization: Bearer YOUR_API_TOKEN" \\
|
||||
-H "Accept: application/json" \\
|
||||
https://your-panel.example.com/panel/api/inbounds/list`;
|
||||
|
||||
const basePath = window.X_UI_BASE_PATH || '';
|
||||
const settingsHref = `${basePath}panel/settings#security`;
|
||||
|
||||
const endpointCount = (allSections as Section[]).reduce(
|
||||
(sum, s) => sum + s.endpoints.length,
|
||||
0,
|
||||
);
|
||||
const openApiUrl = `${basePath}panel/api/openapi.json`;
|
||||
|
||||
export default function ApiDocsPage() {
|
||||
const { isDark, isUltra, antdThemeConfig } = useTheme();
|
||||
|
||||
const [searchQuery, setSearchQuery] = useState('');
|
||||
const [collapsedSections, setCollapsedSections] = useState<Set<string>>(() => new Set());
|
||||
const [activeSection, setActiveSection] = useState('');
|
||||
|
||||
const sections = useMemo<Section[]>(() => {
|
||||
const q = searchQuery.toLowerCase().trim();
|
||||
if (!q) return allSections as Section[];
|
||||
return (allSections as Section[])
|
||||
.map((s) => ({
|
||||
...s,
|
||||
endpoints: s.endpoints.filter((e) =>
|
||||
e.path.toLowerCase().includes(q)
|
||||
|| e.summary?.toLowerCase().includes(q)
|
||||
|| e.method.toLowerCase().includes(q),
|
||||
),
|
||||
}))
|
||||
.filter((s) => s.endpoints.length > 0);
|
||||
}, [searchQuery]);
|
||||
|
||||
const visibleEndpoints = useMemo(
|
||||
() => sections.reduce((sum, s) => sum + s.endpoints.length, 0),
|
||||
[sections],
|
||||
);
|
||||
|
||||
const toggleSection = useCallback((id: string) => {
|
||||
setCollapsedSections((prev) => {
|
||||
const next = new Set(prev);
|
||||
if (next.has(id)) next.delete(id); else next.add(id);
|
||||
return next;
|
||||
});
|
||||
}, []);
|
||||
|
||||
const expandAll = useCallback(() => setCollapsedSections(new Set()), []);
|
||||
const collapseAll = useCallback(
|
||||
() => setCollapsedSections(new Set((allSections as Section[]).map((s) => s.id))),
|
||||
[],
|
||||
);
|
||||
|
||||
const scrollToSection = useCallback((id: string) => (e: MouseEvent) => {
|
||||
e.preventDefault();
|
||||
const el = document.getElementById(id);
|
||||
if (!el) return;
|
||||
el.scrollIntoView({ behavior: 'smooth', block: 'start' });
|
||||
if (window.location.hash !== `#${id}`) {
|
||||
history.replaceState(null, '', `#${id}`);
|
||||
}
|
||||
}, []);
|
||||
|
||||
useEffect(() => {
|
||||
const onHashChange = () => {
|
||||
const id = window.location.hash.slice(1);
|
||||
if (!id) return;
|
||||
const el = document.getElementById(id);
|
||||
if (el) el.scrollIntoView({ behavior: 'auto', block: 'start' });
|
||||
};
|
||||
requestAnimationFrame(onHashChange);
|
||||
window.addEventListener('hashchange', onHashChange);
|
||||
return () => window.removeEventListener('hashchange', onHashChange);
|
||||
}, []);
|
||||
|
||||
useEffect(() => {
|
||||
const onScroll = () => {
|
||||
const toc = document.querySelector('.toc-nav');
|
||||
const tocHeight = toc instanceof HTMLElement ? toc.offsetHeight : 56;
|
||||
let current = '';
|
||||
for (const s of sections) {
|
||||
const el = document.getElementById(s.id);
|
||||
if (!el) continue;
|
||||
const rect = el.getBoundingClientRect();
|
||||
if (rect.top <= tocHeight + 20) {
|
||||
current = s.id;
|
||||
}
|
||||
}
|
||||
setActiveSection(current);
|
||||
};
|
||||
window.addEventListener('scroll', onScroll, { passive: true });
|
||||
requestAnimationFrame(onScroll);
|
||||
return () => window.removeEventListener('scroll', onScroll);
|
||||
}, [sections]);
|
||||
|
||||
const pageClass = useMemo(() => {
|
||||
const classes = ['api-docs-page'];
|
||||
if (isDark) classes.push('is-dark');
|
||||
|
|
@ -152,91 +29,12 @@ export default function ApiDocsPage() {
|
|||
<Layout className="content-shell">
|
||||
<Layout.Content className="content-area">
|
||||
<div className="docs-wrapper">
|
||||
<header className="docs-header">
|
||||
<h1 className="docs-title">API Documentation</h1>
|
||||
<p className="docs-lead">
|
||||
The 3x-ui panel exposes a REST API under <code>/panel/api/</code>. Authenticate with the panel session
|
||||
cookie, or with the <code>Authorization: Bearer <token></code> header below. Every endpoint
|
||||
returns a uniform <code>{'{ success, msg, obj }'}</code> envelope unless otherwise noted.
|
||||
</p>
|
||||
</header>
|
||||
|
||||
<Card className="token-card" size="small">
|
||||
<div className="token-card-head">
|
||||
<div className="token-card-title">
|
||||
<KeyOutlined />
|
||||
<span>API Tokens</span>
|
||||
</div>
|
||||
<Button type="primary" size="small" href={settingsHref}>
|
||||
Manage tokens
|
||||
</Button>
|
||||
</div>
|
||||
<p className="token-hint">
|
||||
Create, enable, or revoke named Bearer tokens in{' '}
|
||||
<a href={settingsHref}>Settings → Security</a>. Send each request as{' '}
|
||||
<code>Authorization: Bearer <token></code>. Token-authenticated callers skip CSRF and don't
|
||||
need a session cookie. Deleting a token revokes it immediately — running bots will need a new one.
|
||||
</p>
|
||||
</Card>
|
||||
|
||||
<Card className="curl-card" size="small" title="Quick example">
|
||||
<CodeBlock code={curlExample} lang="text" />
|
||||
</Card>
|
||||
|
||||
<div className="toolbar">
|
||||
<Input
|
||||
className="search-bar"
|
||||
prefix={<SearchOutlined />}
|
||||
placeholder="Search endpoints by path, method, or description…"
|
||||
allowClear
|
||||
value={searchQuery}
|
||||
onChange={(e) => setSearchQuery(e.target.value)}
|
||||
/>
|
||||
{searchQuery && (
|
||||
<span className="match-count">
|
||||
{visibleEndpoints} / {endpointCount} endpoints
|
||||
</span>
|
||||
)}
|
||||
<Space size="small">
|
||||
<Button size="small" icon={<ExpandOutlined />} onClick={expandAll}>
|
||||
Expand all
|
||||
</Button>
|
||||
<Button size="small" icon={<CompressOutlined />} onClick={collapseAll}>
|
||||
Collapse all
|
||||
</Button>
|
||||
</Space>
|
||||
</div>
|
||||
|
||||
<nav className="toc-nav">
|
||||
<span className="toc-label">On this page:</span>
|
||||
<div className="toc-links">
|
||||
{sections.map((s) => {
|
||||
const Icon = sectionIcons[s.id];
|
||||
return (
|
||||
<a
|
||||
key={s.id}
|
||||
className={`toc-link${activeSection === s.id ? ' active' : ''}`}
|
||||
href={`#${s.id}`}
|
||||
onClick={scrollToSection(s.id)}
|
||||
>
|
||||
{Icon && <Icon />}
|
||||
<span className="toc-text">{s.title}</span>
|
||||
<span className="toc-badge">{s.endpoints.length}</span>
|
||||
</a>
|
||||
);
|
||||
})}
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
{sections.map((s) => (
|
||||
<EndpointSection
|
||||
key={s.id}
|
||||
section={s}
|
||||
icon={sectionIcons[s.id]}
|
||||
collapsed={collapsedSections.has(s.id)}
|
||||
onToggle={() => toggleSection(s.id)}
|
||||
/>
|
||||
))}
|
||||
<SwaggerUI
|
||||
url={openApiUrl}
|
||||
docExpansion="list"
|
||||
deepLinking
|
||||
tryItOutEnabled
|
||||
/>
|
||||
</div>
|
||||
</Layout.Content>
|
||||
</Layout>
|
||||
|
|
|
|||
|
|
@ -1,107 +0,0 @@
|
|||
.code-block-wrapper {
|
||||
position: relative;
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
border: 1px solid rgba(128, 128, 128, 0.15);
|
||||
}
|
||||
|
||||
.code-toolbar {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
padding: 4px 8px;
|
||||
background: rgba(128, 128, 128, 0.06);
|
||||
border-bottom: 1px solid rgba(128, 128, 128, 0.1);
|
||||
}
|
||||
|
||||
.lang-badge {
|
||||
font-size: 10px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.5px;
|
||||
color: rgba(0, 0, 0, 0.4);
|
||||
text-transform: uppercase;
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
}
|
||||
|
||||
.copy-btn {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 26px;
|
||||
height: 26px;
|
||||
border: 1px solid rgba(128, 128, 128, 0.15);
|
||||
border-radius: 4px;
|
||||
background: rgba(255, 255, 255, 0.7);
|
||||
color: rgba(0, 0, 0, 0.45);
|
||||
cursor: pointer;
|
||||
font-size: 12px;
|
||||
transition: all 0.15s;
|
||||
}
|
||||
|
||||
.copy-btn:hover {
|
||||
background: #fff;
|
||||
color: #1677ff;
|
||||
border-color: #1677ff;
|
||||
}
|
||||
|
||||
.copy-btn.copied {
|
||||
background: #52c41a;
|
||||
color: #fff;
|
||||
border-color: #52c41a;
|
||||
}
|
||||
|
||||
.code-block {
|
||||
background: rgba(128, 128, 128, 0.04);
|
||||
padding: 10px 12px;
|
||||
margin: 0;
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 12.5px;
|
||||
line-height: 1.6;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-word;
|
||||
overflow-x: auto;
|
||||
border: none;
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.json-key { color: #0550ae; }
|
||||
.json-string { color: #116329; }
|
||||
.json-number { color: #9a6700; }
|
||||
.json-boolean { color: #cf222e; }
|
||||
.json-null { color: #8250df; }
|
||||
|
||||
body.dark .code-block-wrapper {
|
||||
border-color: rgba(255, 255, 255, 0.1);
|
||||
}
|
||||
|
||||
body.dark .code-toolbar {
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
border-color: rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
||||
body.dark .lang-badge {
|
||||
color: rgba(255, 255, 255, 0.4);
|
||||
}
|
||||
|
||||
body.dark .code-block {
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
color: rgba(255, 255, 255, 0.88);
|
||||
}
|
||||
|
||||
body.dark .json-key { color: #79c0ff; }
|
||||
body.dark .json-string { color: #7ee787; }
|
||||
body.dark .json-number { color: #d29922; }
|
||||
body.dark .json-boolean { color: #ff7b72; }
|
||||
body.dark .json-null { color: #d2a8ff; }
|
||||
|
||||
body.dark .copy-btn {
|
||||
background: rgba(255, 255, 255, 0.06);
|
||||
color: rgba(255, 255, 255, 0.45);
|
||||
border-color: rgba(255, 255, 255, 0.12);
|
||||
}
|
||||
|
||||
body.dark .copy-btn:hover {
|
||||
background: rgba(255, 255, 255, 0.1);
|
||||
color: #58a6ff;
|
||||
border-color: #58a6ff;
|
||||
}
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
import { useMemo, useState } from 'react';
|
||||
import { message } from 'antd';
|
||||
import { CheckOutlined, CopyOutlined } from '@ant-design/icons';
|
||||
import { ClipboardManager } from '@/utils';
|
||||
import './CodeBlock.css';
|
||||
|
||||
interface CodeBlockProps {
|
||||
code?: string;
|
||||
lang?: string;
|
||||
}
|
||||
|
||||
function escapeHtml(str: string): string {
|
||||
return str.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
|
||||
}
|
||||
|
||||
function highlightJson(str: string): string {
|
||||
const escaped = escapeHtml(str);
|
||||
return escaped.replace(
|
||||
/("(?:[^"\\]|\\.)*")\s*(:)|("(?:[^"\\]|\\.)*")|(-?\d+\.?\d*(?:[eE][+-]?\d+)?)\b|(true|false)|(null)|([{}[\]])/g,
|
||||
(_m, key, colon, string, number, bool, nil) => {
|
||||
if (colon) return `<span class="json-key">${key}</span>${colon}`;
|
||||
if (string) return `<span class="json-string">${string}</span>`;
|
||||
if (number) return `<span class="json-number">${number}</span>`;
|
||||
if (bool) return `<span class="json-boolean">${bool}</span>`;
|
||||
if (nil) return `<span class="json-null">${nil}</span>`;
|
||||
return _m;
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
export default function CodeBlock({ code = '', lang = 'json' }: CodeBlockProps) {
|
||||
const [copied, setCopied] = useState(false);
|
||||
const [messageApi, messageContextHolder] = message.useMessage();
|
||||
|
||||
const highlighted = useMemo(
|
||||
() => (lang === 'json' ? highlightJson(code) : escapeHtml(code)),
|
||||
[code, lang],
|
||||
);
|
||||
|
||||
async function copyCode() {
|
||||
const ok = await ClipboardManager.copyText(code);
|
||||
if (ok) {
|
||||
setCopied(true);
|
||||
messageApi.success('Copied');
|
||||
window.setTimeout(() => setCopied(false), 2000);
|
||||
} else {
|
||||
messageApi.error('Copy failed');
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="code-block-wrapper">
|
||||
{messageContextHolder}
|
||||
<div className="code-toolbar">
|
||||
<span className="lang-badge">{lang.toUpperCase()}</span>
|
||||
<button
|
||||
className={`copy-btn${copied ? ' copied' : ''}`}
|
||||
onClick={copyCode}
|
||||
title={copied ? 'Copied' : 'Copy'}
|
||||
>
|
||||
{copied ? <CheckOutlined /> : <CopyOutlined />}
|
||||
</button>
|
||||
</div>
|
||||
<pre className={`code-block lang-${lang}`}>
|
||||
<code dangerouslySetInnerHTML={{ __html: highlighted }} />
|
||||
</pre>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,93 +0,0 @@
|
|||
.endpoint-row {
|
||||
padding: 14px 8px;
|
||||
margin: 0 -8px;
|
||||
transition: background 0.15s;
|
||||
border-radius: 6px;
|
||||
}
|
||||
|
||||
.endpoint-row:hover {
|
||||
background: rgba(128, 128, 128, 0.03);
|
||||
}
|
||||
|
||||
.endpoint-row + .endpoint-row {
|
||||
border-top: 1px solid rgba(128, 128, 128, 0.1);
|
||||
}
|
||||
|
||||
.endpoint-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.method-tag {
|
||||
font-weight: 700;
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 11px;
|
||||
letter-spacing: 0.5px;
|
||||
min-width: 56px;
|
||||
text-align: center;
|
||||
text-transform: uppercase;
|
||||
border-radius: 4px;
|
||||
padding: 2px 8px;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.endpoint-path {
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 13.5px;
|
||||
word-break: break-all;
|
||||
color: rgba(0, 0, 0, 0.8);
|
||||
background: rgba(128, 128, 128, 0.06);
|
||||
padding: 2px 8px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
.endpoint-summary {
|
||||
margin: 8px 0 0;
|
||||
color: rgba(0, 0, 0, 0.6);
|
||||
line-height: 1.6;
|
||||
font-size: 13.5px;
|
||||
}
|
||||
|
||||
.endpoint-block {
|
||||
margin-top: 14px;
|
||||
}
|
||||
|
||||
.block-label {
|
||||
font-size: 11px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.6px;
|
||||
color: rgba(0, 0, 0, 0.45);
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
|
||||
.error-label {
|
||||
color: #cf222e;
|
||||
}
|
||||
|
||||
body.dark .endpoint-row:hover {
|
||||
background: rgba(255, 255, 255, 0.02);
|
||||
}
|
||||
|
||||
body.dark .endpoint-row + .endpoint-row {
|
||||
border-top-color: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
body.dark .endpoint-path {
|
||||
color: rgba(255, 255, 255, 0.82);
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
}
|
||||
|
||||
body.dark .endpoint-summary {
|
||||
color: rgba(255, 255, 255, 0.65);
|
||||
}
|
||||
|
||||
body.dark .block-label {
|
||||
color: rgba(255, 255, 255, 0.45);
|
||||
}
|
||||
|
||||
body.dark .error-label {
|
||||
color: #ff7b72;
|
||||
}
|
||||
|
|
@ -1,84 +0,0 @@
|
|||
import { Table, Tag } from 'antd';
|
||||
import type { ColumnsType } from 'antd/es/table';
|
||||
import { methodColors, safeInlineHtml } from './endpoints.js';
|
||||
import CodeBlock from './CodeBlock';
|
||||
import './EndpointRow.css';
|
||||
|
||||
interface Param {
|
||||
name: string;
|
||||
in?: string;
|
||||
type?: string;
|
||||
desc?: string;
|
||||
}
|
||||
|
||||
export interface Endpoint {
|
||||
method: string;
|
||||
path: string;
|
||||
summary?: string;
|
||||
params?: Param[];
|
||||
body?: string;
|
||||
response?: string;
|
||||
errorResponse?: string;
|
||||
}
|
||||
|
||||
const paramColumns: ColumnsType<Param> = [
|
||||
{ title: 'Name', dataIndex: 'name', key: 'name', width: 180 },
|
||||
{ title: 'In', dataIndex: 'in', key: 'in', width: 100 },
|
||||
{ title: 'Type', dataIndex: 'type', key: 'type', width: 120 },
|
||||
{ title: 'Description', dataIndex: 'desc', key: 'desc' },
|
||||
];
|
||||
|
||||
export default function EndpointRow({ endpoint }: { endpoint: Endpoint }) {
|
||||
const tagColor = (methodColors as Record<string, string>)[endpoint.method] || 'default';
|
||||
const hasParams = Array.isArray(endpoint.params) && endpoint.params.length > 0;
|
||||
|
||||
return (
|
||||
<div className="endpoint-row">
|
||||
<div className="endpoint-header">
|
||||
<Tag color={tagColor} className="method-tag">{endpoint.method}</Tag>
|
||||
<code className="endpoint-path">{endpoint.path}</code>
|
||||
</div>
|
||||
|
||||
{endpoint.summary && (
|
||||
<p
|
||||
className="endpoint-summary"
|
||||
dangerouslySetInnerHTML={{ __html: safeInlineHtml(endpoint.summary) }}
|
||||
/>
|
||||
)}
|
||||
|
||||
{hasParams && (
|
||||
<div className="endpoint-block">
|
||||
<div className="block-label">Parameters</div>
|
||||
<Table
|
||||
columns={paramColumns}
|
||||
dataSource={endpoint.params}
|
||||
pagination={false}
|
||||
size="small"
|
||||
rowKey="name"
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{endpoint.body && (
|
||||
<div className="endpoint-block">
|
||||
<div className="block-label">Request body</div>
|
||||
<CodeBlock code={endpoint.body} lang="json" />
|
||||
</div>
|
||||
)}
|
||||
|
||||
{endpoint.response && (
|
||||
<div className="endpoint-block">
|
||||
<div className="block-label">Response</div>
|
||||
<CodeBlock code={endpoint.response} lang="json" />
|
||||
</div>
|
||||
)}
|
||||
|
||||
{endpoint.errorResponse && (
|
||||
<div className="endpoint-block">
|
||||
<div className="block-label error-label">Error response</div>
|
||||
<CodeBlock code={endpoint.errorResponse} lang="json" />
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,129 +0,0 @@
|
|||
.api-section {
|
||||
background: #fff;
|
||||
border: 1px solid rgba(128, 128, 128, 0.12);
|
||||
border-radius: 8px;
|
||||
padding: 20px 24px;
|
||||
margin-bottom: 16px;
|
||||
transition: box-shadow 0.2s, border-color 0.2s;
|
||||
}
|
||||
|
||||
.api-section:hover {
|
||||
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.06);
|
||||
}
|
||||
|
||||
.section-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
cursor: pointer;
|
||||
user-select: none;
|
||||
}
|
||||
|
||||
.section-header:hover .collapse-icon,
|
||||
.section-header:hover .section-icon {
|
||||
color: #1677ff;
|
||||
}
|
||||
|
||||
.section-header-left {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
.collapse-icon {
|
||||
font-size: 12px;
|
||||
color: rgba(0, 0, 0, 0.4);
|
||||
transition: color 0.2s;
|
||||
}
|
||||
|
||||
.section-icon {
|
||||
font-size: 18px;
|
||||
color: rgba(0, 0, 0, 0.45);
|
||||
transition: color 0.2s;
|
||||
}
|
||||
|
||||
.section-title {
|
||||
font-size: 20px;
|
||||
font-weight: 700;
|
||||
margin: 0;
|
||||
color: rgba(0, 0, 0, 0.88);
|
||||
}
|
||||
|
||||
.endpoint-count {
|
||||
font-size: 11px;
|
||||
font-weight: 600;
|
||||
color: rgba(0, 0, 0, 0.45);
|
||||
white-space: nowrap;
|
||||
background: rgba(128, 128, 128, 0.08);
|
||||
padding: 3px 10px;
|
||||
border-radius: 12px;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.3px;
|
||||
}
|
||||
|
||||
.section-description {
|
||||
margin: 12px 0 14px;
|
||||
color: rgba(0, 0, 0, 0.65);
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.sub-header-block {
|
||||
margin-bottom: 14px;
|
||||
}
|
||||
|
||||
.section-block-label {
|
||||
font-size: 12px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
color: rgba(0, 0, 0, 0.5);
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
|
||||
.endpoints {
|
||||
padding-top: 8px;
|
||||
border-top: 1px solid rgba(128, 128, 128, 0.1);
|
||||
}
|
||||
|
||||
.endpoints > :first-child {
|
||||
padding-top: 0;
|
||||
}
|
||||
|
||||
body.dark .api-section {
|
||||
background: #252526;
|
||||
border-color: rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
body.dark .api-section:hover {
|
||||
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.25);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .api-section {
|
||||
background: #0a0a0a;
|
||||
border-color: rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
||||
html[data-theme='ultra-dark'] .api-section:hover {
|
||||
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.4);
|
||||
}
|
||||
|
||||
body.dark .section-title {
|
||||
color: rgba(255, 255, 255, 0.92);
|
||||
}
|
||||
|
||||
body.dark .section-icon {
|
||||
color: rgba(255, 255, 255, 0.5);
|
||||
}
|
||||
|
||||
body.dark .section-description {
|
||||
color: rgba(255, 255, 255, 0.7);
|
||||
}
|
||||
|
||||
body.dark .section-block-label {
|
||||
color: rgba(255, 255, 255, 0.55);
|
||||
}
|
||||
|
||||
body.dark .endpoint-count {
|
||||
color: rgba(255, 255, 255, 0.55);
|
||||
background: rgba(255, 255, 255, 0.06);
|
||||
}
|
||||
|
|
@ -1,90 +0,0 @@
|
|||
import type { ComponentType } from 'react';
|
||||
import { Table } from 'antd';
|
||||
import type { ColumnsType } from 'antd/es/table';
|
||||
import { DownOutlined, RightOutlined } from '@ant-design/icons';
|
||||
import EndpointRow from './EndpointRow';
|
||||
import type { Endpoint } from './EndpointRow';
|
||||
import { safeInlineHtml } from './endpoints.js';
|
||||
import './EndpointSection.css';
|
||||
|
||||
interface SubHeader {
|
||||
name: string;
|
||||
desc?: string;
|
||||
}
|
||||
|
||||
export interface Section {
|
||||
id: string;
|
||||
title: string;
|
||||
description?: string;
|
||||
endpoints: Endpoint[];
|
||||
subHeader?: SubHeader[];
|
||||
}
|
||||
|
||||
interface EndpointSectionProps {
|
||||
section: Section;
|
||||
icon?: ComponentType<{ className?: string }> | null;
|
||||
collapsed?: boolean;
|
||||
onToggle?: () => void;
|
||||
}
|
||||
|
||||
const subHeaderColumns: ColumnsType<SubHeader> = [
|
||||
{ title: 'Header', dataIndex: 'name', key: 'name', width: 240 },
|
||||
{
|
||||
title: 'Description',
|
||||
dataIndex: 'desc',
|
||||
key: 'desc',
|
||||
render: (value: string) => (
|
||||
<span dangerouslySetInnerHTML={{ __html: safeInlineHtml(value || '') }} />
|
||||
),
|
||||
},
|
||||
];
|
||||
|
||||
export default function EndpointSection({
|
||||
section,
|
||||
icon: Icon = null,
|
||||
collapsed = false,
|
||||
onToggle,
|
||||
}: EndpointSectionProps) {
|
||||
const endpointLabel = section.endpoints.length === 1
|
||||
? '1 endpoint'
|
||||
: `${section.endpoints.length} endpoints`;
|
||||
|
||||
return (
|
||||
<section id={section.id} className="api-section">
|
||||
<div className="section-header" onClick={onToggle}>
|
||||
<div className="section-header-left">
|
||||
{collapsed ? <RightOutlined className="collapse-icon" /> : <DownOutlined className="collapse-icon" />}
|
||||
{Icon && <Icon className="section-icon" />}
|
||||
<h2 className="section-title">{section.title}</h2>
|
||||
</div>
|
||||
<span className="endpoint-count">{endpointLabel}</span>
|
||||
</div>
|
||||
|
||||
{section.description && !collapsed && (
|
||||
<p
|
||||
className="section-description"
|
||||
dangerouslySetInnerHTML={{ __html: safeInlineHtml(section.description) }}
|
||||
/>
|
||||
)}
|
||||
|
||||
{section.subHeader && !collapsed && (
|
||||
<div className="sub-header-block">
|
||||
<div className="section-block-label">Response headers</div>
|
||||
<Table
|
||||
columns={subHeaderColumns}
|
||||
dataSource={section.subHeader}
|
||||
pagination={false}
|
||||
size="small"
|
||||
rowKey="name"
|
||||
/>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className="endpoints" style={{ display: collapsed ? 'none' : undefined }}>
|
||||
{section.endpoints.map((endpoint, idx) => (
|
||||
<EndpointRow key={idx} endpoint={endpoint} />
|
||||
))}
|
||||
</div>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
|
|
@ -198,6 +198,11 @@ export default defineConfig({
|
|||
if (id.includes('/node_modules/otpauth/')) return 'vendor-otpauth';
|
||||
if (id.includes('/node_modules/@tanstack/')) return 'vendor-tanstack';
|
||||
if (id.includes('/node_modules/react-router')) return 'vendor-router';
|
||||
if (
|
||||
id.includes('/node_modules/swagger-ui-react/')
|
||||
|| id.includes('/node_modules/swagger-ui/')
|
||||
|| id.includes('/node_modules/swagger-client/')
|
||||
) return 'vendor-swagger';
|
||||
if (id.includes('dayjs')) return 'vendor-dayjs';
|
||||
if (id.includes('axios')) return 'vendor-axios';
|
||||
return 'vendor';
|
||||
|
|
|
|||
|
|
@ -23,6 +23,21 @@ func SetDistFS(fs embed.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 {
|
||||
|
|
|
|||
|
|
@ -227,6 +227,7 @@ func (s *Server) initRouter() (*gin.Engine, error) {
|
|||
|
||||
s.index = controller.NewIndexController(g)
|
||||
s.panel = controller.NewXUIController(g)
|
||||
g.GET("/panel/api/openapi.json", controller.ServeOpenAPISpec)
|
||||
s.api = controller.NewAPIController(g, s.customGeoService)
|
||||
|
||||
// Initialize WebSocket hub
|
||||
|
|
|
|||
Loading…
Reference in a new issue