docs: refine built-in docs try it out

Author: rockyshi1993

README.md

@@ -646,7 +646,7 @@ Projects can override or add source definitions with `openapi.docs.sources`; sou
 
 The operation view includes parameters, request bodies, horizontal response status tabs without repeated status headings, resolved schema fields without artificial root rows, search entries, auth/deprecated/Try it out state badges, collapsed operation Metadata, a global Authorize control for OpenAPI security schemes, same-origin Try it out, and Code JSDoc usage recipes.
 
-The Try it out console is organized as tabs for Params, Headers, Body, Auth, Samples, History, and Response. It includes server selection, OpenAPI `servers[].variables` controls, full resolved URL preview and Copy URL, structured query/header rows generated from OpenAPI parameters including `validate.header`, raw fallbacks, auth injection notes, optional browser-side request/response hooks through `openapi.docs.tryItOut.hookScript` / `hookGlobal`, diagnostics, cURL/browser fetch/Node fetch/Axios code samples, request history, and a fixed response viewer with pretty/raw body modes plus the actual request and response headers for the last send.
+The Try it out console is organized as tabs for Params, Headers, Body, Samples, History, and Response. It includes server selection that prefers OpenAPI `servers[]`, OpenAPI `servers[].variables` controls, optional same-origin fallback, an optional per-request Custom server input, full resolved URL preview and Copy URL, structured query/header rows generated from OpenAPI parameters including `validate.header`, raw fallbacks, auth status and effective header previews inside the Headers tab, optional browser-side request/response hooks through `openapi.docs.tryItOut.hookScript` / `hookGlobal`, diagnostics, cURL/browser fetch/Node fetch/Axios code samples, request history, and a fixed response viewer with pretty/raw body modes plus the actual request and response headers for the last send.
 
 `hookGlobal` is only the browser lookup name; hook notes and sample diagnostics are shown only when a `hookScript` is configured or the runtime global exposes `beforeRequest` / `afterResponse`.
 
@@ -741,6 +741,32 @@ window.VextDocsHooks = {
 
 Enable it with `openapi.docs.tryItOut.hookScript = "/docs-hook.js"` and optionally change the lookup name with `hookGlobal`.
 
+Try it out server behavior can be tuned separately from the OpenAPI `servers[]` metadata:
+
+```ts
+export default {
+  openapi: {
+    servers: [
+      {
+        url: "http://127.0.0.1:3000",
+        description: "Local development server",
+      },
+      { url: "https://api.example.com", description: "Production" },
+    ],
+    docs: {
+      tryItOut: {
+        defaultServer: "first", // "first", "same-origin", "custom", or an exact server URL
+        sameOrigin: "auto", // auto shows Same origin only when no OpenAPI servers exist
+        customServer: true,
+        customServerUrl: "http://127.0.0.1:3000",
+      },
+    },
+  },
+};
+```
+
+For fixed local or deployed endpoints, prefer a complete server URL including its port. Reserve OpenAPI `servers[].variables` for genuinely variable parts such as environment names, regions, tenants, or API versions.
+
 ## i18n
 
 Put locale files in `src/locales/`:

changelogs/unreleased.md

@@ -14,11 +14,13 @@
 - **Built-in docs renderer proxy paths** Added `openapi.docs.assetsPublicPath` for prefix-stripping reverse proxies, so browser-facing docs assets and source-aware data endpoints can differ from Vext's internal `docs.assetsPath`; validation now checks `source.access` field shapes and the docs clarify that `jsonPublicPath` is the public canonical OpenAPI spec URL rather than the built-in source-aware data endpoint.
 - **Built-in docs Try it out** Added OpenAPI server variable controls and browser-side request hooks. Try it out now resolves `servers[].variables` into URL previews, Copy URL, samples, and Send requests, validates enum/default values, can load an optional `openapi.docs.tryItOut.hookScript`, calls `window[hookGlobal].beforeRequest` / `afterResponse` around the browser fetch pipeline, and shows hook diagnostics without importing or executing backend project code.
 - **Built-in docs Try it out** Clarified hook UI behavior so `hookGlobal` alone is treated as a browser lookup name; hook notes and sample diagnostics are shown only when a hook script is configured or the runtime global actually exposes `beforeRequest` / `afterResponse`.
+- **Built-in docs Try it out** Refined server selection so OpenAPI `servers[]` are preferred by default, `Same origin` is configurable through `openapi.docs.tryItOut.sameOrigin`, users can temporarily enter a Custom server URL, server variable panels are hidden when empty, fixed local endpoints are documented and tested as complete server URLs instead of `{port}` variables, and `/docs` renders an inline critical loading shell during refresh/source loading instead of showing a blank page.
+- **Built-in docs Try it out** Removed the separate Auth tab and merged auth state into the Headers tab, where Authorize-injected credentials, manual header overrides, and the effective headers preview can be checked in one place.
 - **Built-in docs renderer UI** Fixed code-doc navigation indentation so plugin/middleware leaves align under their parent tree instead of the top-level caret, distinguishes default and named plugin/middleware symbols such as `stats.increment`, renders multi-line JSDoc descriptions as paragraphs/lists/code blocks in vanilla JS, and adds an inline favicon to keep `/docs` browser probes free of favicon 404 noise.
 - **Built-in docs renderer UI** Polished the default docs interaction model by rendering HTTP API / Pages operation cards directly without tag section headings such as `General`, reducing root navigation guide lines, keeping Try it out results in a fixed scrollable output area to avoid Send-time layout jumps, moving Try it out tabs before Send actions, stacking the header so the title, search box, filters, and global Authorize panel do not compete for one row, adding hover/focus feedback to API and code cards, flattening the Overview shell, using the outline only on wide screens, improving mobile navigation, and making the desktop sidebar auto-sized with persisted manual resize.
 - **Built-in docs renderer UI** Refined the default docs experience with `openapi.docs.ui.theme` / `density`, preserved middle dynamic path segments when they lead to stable child resources, added keyboard search shortcuts, category filters, highlighted matches, a desktop outline, copy buttons, deep links, and an Overview workspace with counts, OpenAPI source, access mode, and asset version metadata.
 - **Built-in docs renderer UI** Simplified the default documentation surface by hiding Locales / Config / Styles / Preload from the default top-level navigation unless explicitly enabled as static code sources, moving filters to their own header row, and adding package startup/build/verification commands to the Overview workspace.
-- **Built-in docs Try it out** Upgraded each operation console with server selection, full URL preview plus Copy URL, tabbed Params / Headers / Body / Auth / Samples / History / Response panels, structured query/header rows plus raw fallbacks, compact empty states, auth injection notes, cURL/browser fetch/Node fetch/Axios samples with copy actions, local request history that does not persist automatically injected Authorize tokens, and a fixed response viewer with pretty/raw body modes.
+- **Built-in docs Try it out** Upgraded each operation console with server selection, full URL preview plus Copy URL, tabbed Params / Headers / Body / Samples / History / Response panels, structured query/header rows plus raw fallbacks, compact empty states, auth status and effective header previews in the Headers tab, cURL/browser fetch/Node fetch/Axios samples with copy actions, local request history that does not persist automatically injected Authorize tokens, and a fixed response viewer with pretty/raw body modes.
 - **Built-in docs Try it out** Fixed request header usability by exporting `validate.header` as OpenAPI `parameters[in=header]`, pre-filling those headers in the console, showing the actual sent request headers alongside response headers, and keeping the Send status in a stable inline slot to avoid response-area flicker.
 
 ## 2026-06-23

src/lib/config-loader.ts

@@ -1147,6 +1147,18 @@ function validateDocsTryItOutConfig(value: unknown, pathName: string): void {
   }
   validateOptionalString(tryItOut.hookScript, `${pathName}.hookScript`);
   validateOptionalString(tryItOut.hookGlobal, `${pathName}.hookGlobal`);
+  validateOptionalString(tryItOut.defaultServer, `${pathName}.defaultServer`);
+  validateOptionalBoolean(tryItOut.customServer, `${pathName}.customServer`);
+  validateOptionalString(tryItOut.customServerUrl, `${pathName}.customServerUrl`);
+  if (
+    tryItOut.sameOrigin !== undefined &&
+    typeof tryItOut.sameOrigin !== "boolean" &&
+    tryItOut.sameOrigin !== "auto"
+  ) {
+    throw new Error(
+      `[vextjs] ${pathName}.sameOrigin must be a boolean or "auto".`,
+    );
+  }
 }
 
 function validateOpenAPIServers(value: unknown, pathName: string): void {

src/lib/docs/normalize-config.ts

@@ -172,6 +172,10 @@ export function normalizeDocsConfig(
   const tryItOut: ResolvedVextDocsTryItOutConfig = {
     hookScript: openapi.docs?.tryItOut?.hookScript,
     hookGlobal: openapi.docs?.tryItOut?.hookGlobal ?? "VextDocsHooks",
+    defaultServer: openapi.docs?.tryItOut?.defaultServer,
+    sameOrigin: openapi.docs?.tryItOut?.sameOrigin ?? "auto",
+    customServer: openapi.docs?.tryItOut?.customServer ?? true,
+    customServerUrl: openapi.docs?.tryItOut?.customServerUrl,
   };
   const renderer = openapi.docs?.renderer;
   if (renderer !== undefined && renderer !== DEFAULT_DOCS_RENDERER) {