Advanced system-level configuration and architecture components for Swagger UI's core functionality.
Core system class that manages plugin architecture, state management, and rendering.
/** System constructor and configuration */
class System {
/** Create new system instance with options */
constructor(options: SystemOptions): System;
/** Register plugins with the system */
register(plugins: any[]): void;
/** Get configured system instance */
getSystem(): SwaggerUISystem;
/** Render UI component to DOM node */
render(domNode: Element, componentName: string): void;
/** Update system configuration */
setConfigs(options: object): void;
}
interface SystemOptions {
/** Plugin presets to load */
presets?: any[];
/** Individual plugins to load */
plugins?: any[];
/** Initial Redux state */
initialState?: object;
/** Custom reducers */
reducers?: object;
/** Custom middleware */
middleware?: any[];
}Comprehensive configuration utilities for merging, validation, and type casting.
interface SwaggerUIConfig {
/** Default configuration options */
defaults: SwaggerUIDefaultOptions;
/** Merge multiple configuration objects */
merge(target: object, ...sources: object[]): object;
/** Type cast configuration values */
typeCast(options: object): object;
/** Type casting mappings for option validation */
typeCastMappings: TypeCastMappings;
}
interface TypeCastMappings {
/** String type casting rules */
string: {
[key: string]: (value: any) => string;
};
/** Boolean type casting rules */
boolean: {
[key: string]: (value: any) => boolean;
};
/** Number type casting rules */
number: {
[key: string]: (value: any) => number;
};
/** Array type casting rules */
array: {
[key: string]: (value: any) => any[];
};
}Multiple configuration source handling with precedence management.
/** Configuration source functions */
interface ConfigurationSources {
/** Extract options from URL query parameters */
optionsFromQuery(): (userOptions: object) => object;
/** Extract options from runtime environment */
optionsFromRuntime(): () => object;
/** Load options from external URL */
optionsFromURL(params: { url: string; system: System }): (options: object) => Promise<object>;
}Complete default configuration object with all available options.
interface SwaggerUIDefaultOptions {
/** DOM targeting */
dom_id: null;
domNode: null;
/** API source */
spec: {};
url: "";
urls: null;
configUrl: null;
/** Layout and display */
layout: "BaseLayout";
docExpansion: "list";
maxDisplayedTags: -1;
filter: false;
displayOperationId: false;
displayRequestDuration: false;
deepLinking: false;
showExtensions: false;
showCommonExtensions: false;
/** Models */
defaultModelRendering: "example";
defaultModelExpandDepth: 1;
defaultModelsExpandDepth: 1;
/** Interaction */
tryItOutEnabled: false;
withCredentials: false;
showMutatedRequest: true;
/** Authentication */
oauth2RedirectUrl: undefined;
persistAuthorization: false;
/** Validation */
validatorUrl: "https://validator.swagger.io/validator";
/** Request handling */
requestInterceptor: (request: any) => any;
responseInterceptor: (response: any) => any;
supportedSubmitMethods: string[];
/** Code generation */
requestSnippetsEnabled: false;
requestSnippets: RequestSnippetsConfig;
/** Query configuration */
queryConfigEnabled: false;
/** Plugin system */
presets: any[];
plugins: any[];
initialState: {};
fn: {};
components: {};
/** Styling */
syntaxHighlight: SyntaxHighlightConfig;
/** Sorting */
operationsSorter: null;
tagsSorter: null;
/** Callbacks */
onComplete: null;
modelPropertyMacro: null;
parameterMacro: null;
uncaughtExceptionHandler: null;
/** File uploads */
fileUploadMediaTypes: string[];
}
interface RequestSnippetsConfig {
generators: {
curl_bash: { title: "cURL (bash)"; syntax: "bash" };
curl_powershell: { title: "cURL (PowerShell)"; syntax: "powershell" };
curl_cmd: { title: "cURL (CMD)"; syntax: "bash" };
};
defaultExpanded: true;
languages: string[] | null;
}
interface SyntaxHighlightConfig {
activated: true;
theme: "agate";
}Redux-based state management system with immutable state handling.
/** System state structure */
interface SwaggerUIState {
/** Specification state */
spec: {
json: object;
resolved: object;
url: string;
loadingStatus: "loading" | "success" | "error";
};
/** Authentication state */
auth: {
authorized: object;
showDefinitions: boolean;
};
/** Layout state */
layout: {
isShown: boolean;
showSummary: boolean;
};
/** Filter state */
filter: {
byTag: string;
};
/** Configuration state */
configs: object;
}
/** System actions interface */
interface SwaggerUIActions {
/** Specification actions */
specActions: {
updateSpec: (spec: string) => void;
updateUrl: (url: string) => void;
updateLoadingStatus: (status: string) => void;
download: (url: string) => void;
};
/** Authentication actions */
authActions: {
authorize: (auth: object) => void;
logout: (auth: string[]) => void;
showDefinitions: (show: boolean) => void;
};
/** Configuration actions */
configsActions: {
loaded: () => void;
};
}System-level plugin management and lifecycle handling.
/** Plugin system interface */
interface PluginSystemIntegration {
/** Plugin registration and factorization */
inlinePluginOptionsFactorization: (options: object) => any;
systemOptionsFactorization: (options: object) => SystemOptions;
/** Plugin lifecycle hooks */
pluginLifecycle: {
beforeLoad: (plugin: any) => void;
afterLoad: (plugin: any) => void;
onError: (error: Error, plugin: any) => void;
};
}System Instance Creation:
import { System } from "swagger-ui";
const system = new System({
presets: [SwaggerUI.presets.apis],
plugins: [SwaggerUI.plugins.Auth, SwaggerUI.plugins.RequestSnippets],
initialState: {
spec: {
url: "https://api.example.com/openapi.json"
}
}
});
const configuredSystem = system.getSystem();Configuration Merging:
import SwaggerUI from "swagger-ui";
const baseConfig = SwaggerUI.config.defaults;
const customConfig = {
deepLinking: true,
tryItOutEnabled: true,
requestSnippetsEnabled: true
};
const mergedConfig = SwaggerUI.config.merge({}, baseConfig, customConfig);
const ui = SwaggerUI(mergedConfig);Type Casting Configuration:
const rawConfig = {
deepLinking: "true", // string
maxDisplayedTags: "10", // string
tryItOutEnabled: 1 // number
};
const typedConfig = SwaggerUI.config.typeCast(rawConfig);
// Results in:
// {
// deepLinking: true, // boolean
// maxDisplayedTags: 10, // number
// tryItOutEnabled: true // boolean
// }Advanced System Configuration:
import SwaggerUI from "swagger-ui";
const system = SwaggerUI({
dom_id: '#swagger-ui',
url: 'https://api.example.com/openapi.json',
// Custom request interceptor
requestInterceptor: (request) => {
// Add custom headers
request.headers['X-Custom-Header'] = 'value';
request.curlOptions = ['--verbose'];
return request;
},
// Custom response interceptor
responseInterceptor: (response) => {
// Log responses
console.log('API Response:', response);
return response;
},
// Custom error handler
uncaughtExceptionHandler: (error) => {
console.error('Swagger UI Error:', error);
// Send to error tracking service
},
// Lifecycle callback
onComplete: () => {
console.log('Swagger UI initialization complete');
// Access system state
const state = system.getState();
console.log('Current spec:', state.getIn(['spec', 'json']));
}
});Plugin State Access:
const ui = SwaggerUI({
dom_id: '#swagger-ui',
url: 'https://api.example.com/openapi.json'
});
// Access system after initialization
const system = ui.getSystem();
// Access current state
const currentState = system.getState();
const specJson = currentState.getIn(['spec', 'json']);
const authState = currentState.getIn(['auth', 'authorized']);
// Dispatch actions
system.specActions.updateUrl('https://new-api.example.com/openapi.json');
system.authActions.authorize({
apiKey: { key: 'X-API-Key', value: 'secret-key' }
});