or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md distribution.md index.md plugins.md system.md

tile.json

Distribution Packages

Swagger UI provides multiple distribution formats to support different deployment scenarios and integration patterns.

Capabilities

Main Package (swagger-ui)

The primary npm package designed for use in bundled applications with module resolution.

/** Main entry point - default export */
function SwaggerUI(options: SwaggerUIOptions): SwaggerUISystem;

/** Package exports configuration */
interface SwaggerUIPackageExports {
  /** Main entry point for bundlers */
  ".": {
    browser: {
      import: "./dist/swagger-ui-es-bundle-core.js";
      require: "./dist/swagger-ui.js";
    };
    node: {
      import: "./dist/swagger-ui-bundle.js";
      require: "./dist/swagger-ui-es-bundle.js";
    };
    default: {
      import: "./dist/swagger-ui-bundle.js";
      require: "./dist/swagger-ui-es-bundle.js";
    };
  };
  
  /** CSS stylesheet */
  "./dist/swagger-ui.css": "./dist/swagger-ui.css";
  
  /** OAuth2 redirect handler */
  "./dist/oauth2-redirect.html": "./dist/oauth2-redirect.html";
  
  /** Standalone preset bundle */
  "./dist/swagger-ui-standalone-preset": "./dist/swagger-ui-standalone-preset.js";
}

Distribution Package (swagger-ui-dist)

Dependency-free package containing pre-built assets for server-side projects and static deployments.

/** Main distribution exports */
interface SwaggerUIDistExports {
  /** Complete Swagger UI bundle equivalent to main SwaggerUI function */
  SwaggerUIBundle: typeof SwaggerUI;
  
  /** Standalone preset for static deployments */
  SwaggerUIStandalonePreset: StandalonePreset;
  
  /** Get absolute path to distribution assets */
  absolutePath(): string;
  
  /** Alias for absolutePath (legacy compatibility) */
  getAbsoluteFSPath(): string;
}

/** Standalone preset interface */
interface StandalonePreset {
  /** Top navigation bar component */
  TopBar: React.Component;
  
  /** Complete standalone layout */
  StandaloneLayout: React.Component;
}

Built Assets

Pre-compiled JavaScript and CSS files for direct browser usage.

/** Available built assets */
interface BuiltAssets {
  /** Complete bundle with all dependencies */
  "swagger-ui-bundle.js": JavaScriptBundle;
  
  /** ES module bundle for modern environments */
  "swagger-ui-es-bundle.js": ESModuleBundle;
  
  /** Core ES module bundle (browser-optimized) */
  "swagger-ui-es-bundle-core.js": CoreESModuleBundle;
  
  /** Standalone preset bundle */
  "swagger-ui-standalone-preset.js": StandalonePresetBundle;
  
  /** Main library bundle */
  "swagger-ui.js": MainBundle;
  
  /** Complete stylesheet */
  "swagger-ui.css": Stylesheet;
  
  /** OAuth2 redirect handler */
  "oauth2-redirect.html": HTMLAsset;
  
  /** Default initializer script */
  "swagger-initializer.js": InitializerScript;
}

CDN Usage

Direct browser usage via CDN without package installation.

/** CDN integration patterns */
interface CDNUsage {
  /** UnPkg CDN base URL */
  unpkgBaseUrl: "https://unpkg.com/swagger-ui-dist@{version}/";
  
  /** JSDelivr CDN base URL */
  jsdelivrBaseUrl: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@{version}/";
  
  /** Required assets for browser usage */
  requiredAssets: {
    css: "swagger-ui.css";
    js: "swagger-ui-bundle.js";
    preset?: "swagger-ui-standalone-preset.js";
  };
}

/** Global browser exports */
interface BrowserGlobals {
  /** Main SwaggerUI constructor */
  SwaggerUIBundle: typeof SwaggerUI;
  
  /** Standalone preset (when included) */
  SwaggerUIStandalonePreset?: StandalonePreset;
}

Usage Examples

Main Package (Bundled Applications):

import SwaggerUI from "swagger-ui";
import "swagger-ui/dist/swagger-ui.css";

const ui = SwaggerUI({
  dom_id: '#swagger-ui',
  url: 'https://api.example.com/openapi.json'
});

Distribution Package (Server-Side):

const express = require('express');
const { absolutePath } = require('swagger-ui-dist');

const app = express();

// Serve swagger-ui-dist assets
app.use('/api-docs', express.static(absolutePath()));

app.listen(3000);

Distribution Package (Programmatic):

const { SwaggerUIBundle, SwaggerUIStandalonePreset } = require('swagger-ui-dist');

const ui = SwaggerUIBundle({
  url: "https://api.example.com/openapi.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  layout: "StandaloneLayout"
});

CDN Usage (Basic):

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.28.1/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@5.28.1/swagger-ui-bundle.js"></script>
  <script>
    const ui = SwaggerUIBundle({
      url: 'https://api.example.com/openapi.json',
      dom_id: '#swagger-ui'
    });
  </script>
</body>
</html>

CDN Usage (Standalone):

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.28.1/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@5.28.1/swagger-ui-bundle.js"></script>
  <script src="https://unpkg.com/swagger-ui-dist@5.28.1/swagger-ui-standalone-preset.js"></script>
  <script>
    const ui = SwaggerUIBundle({
      url: 'https://api.example.com/openapi.json',
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout"
    });
  </script>
</body>
</html>

Static File Deployment:

// Copy dist files to your static directory
const { absolutePath } = require('swagger-ui-dist');
const fs = require('fs');
const path = require('path');

const sourceDir = absolutePath();
const targetDir = './public/api-docs';

// Copy all files from swagger-ui-dist
fs.cpSync(sourceDir, targetDir, { recursive: true });

// Modify swagger-initializer.js with your API URL
const initializerPath = path.join(targetDir, 'swagger-initializer.js');
const initializerContent = `
window.onload = function() {
  window.ui = SwaggerUIBundle({
    url: "/api/openapi.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  });
};
`;
fs.writeFileSync(initializerPath, initializerContent);

Docker Environment:

# Pull official Swagger UI Docker image
docker pull swaggerapi/swagger-ui

# Run with external API specification
docker run -p 80:8080 \
  -e SWAGGER_JSON_URL=https://api.example.com/openapi.json \
  swaggerapi/swagger-ui

# Run with local specification file
docker run -p 80:8080 \
  -e SWAGGER_JSON=/app/openapi.json \
  -v $(pwd)/openapi.json:/app/openapi.json \
  swaggerapi/swagger-ui