Swagger UI Deployment and Usage Guide

Prerequisites

• Node.js (version 12 or higher)
• npm (version 6 or higher)
• Git for cloning the repository
• A web browser for viewing the UI
• Optional: Docker for containerized deployment

Installation

Option 1: Using npm (Recommended for Single-Page Applications)

# Install the main package
npm install swagger-ui

# Or install the React component
npm install swagger-ui-react

# Or install the dependency-free distribution
npm install swagger-ui-dist

Option 2: Using Composer (for PHP projects)

composer require swagger-api/swagger-ui

Option 3: Using Docker

docker pull swaggerapi/swagger-ui

Option 4: Manual Download

1. Download the latest release from GitHub Releases
2. Extract the contents
3. Copy the /dist folder to your server

Configuration

Environment Variables

Swagger UI uses Scarf for anonymized analytics. To opt out:

// package.json
{
  "scarfSettings": {
    "enabled": false
  }
}

Or set the environment variable:

export SCARF_SETTINGS_ENABLED=false

API Configuration

Swagger UI requires an OpenAPI specification file. You can configure it in several ways:

1. URL Parameter: http://example.com/?url=http://petstore.swagger.io/v2/swagger.json
2. Configuration Object: Pass a configuration object when initializing
3. File Path: Serve a local OpenAPI specification file

Supported OpenAPI Versions

Swagger UI supports multiple OpenAPI Specification versions:

Build & Run

Development Mode

# Clone the repository
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui

# Install dependencies
npm install

# Start development server
npm run start

Production Build

# Build for production
npm run build

# Serve the built files
# Copy the contents of the /dist folder to your web server

Using swagger-ui-dist

# Install the dependency-free distribution
npm install swagger-ui-dist

# Serve the files from node_modules/swagger-ui-dist
# This directory contains all necessary HTML, CSS, and JavaScript files

Using swagger-ui-react

import React from 'react';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

function App() {
  return <SwaggerUI url="https://petstore.swagger.io/v2/swagger.json" />;
}

Deployment

Static Hosting (Recommended)

Swagger UI is a static web application that can be deployed to any static hosting service:

# Build the application
npm run build

# Deploy the /dist folder to your hosting provider

Supported Platforms:

• Vercel (formerly Zeit Now)
• Netlify
• GitHub Pages
• AWS S3 + CloudFront
• Google Cloud Storage
• Azure Blob Storage

Docker Deployment

# Build the Docker image
docker build -t swagger-ui .

# Run the container
docker run -p 8080:8080 swagger-ui

Server-Side Integration

For server-side projects, use swagger-ui-dist:

const express = require('express');
const path = require('path');
const app = express();

app.use(express.static(path.join(__dirname, 'node_modules/swagger-ui-dist')));

app.listen(3000, () => {
  console.log('Swagger UI served on port 3000');
});

Troubleshooting

Common Issues and Solutions

1. CORS Errors When Loading OpenAPI Specification

Problem: Browser blocks requests to external API specifications due to CORS policy.

Solution: Ensure your API server has proper CORS headers configured, or serve the OpenAPI specification from the same domain.

// Example CORS configuration for Express
app.use((req, res, next) => {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
  next();
});

2. Plugin Loading Issues

Problem: Custom plugins fail to load or cause errors.

Solution: Ensure plugins are properly registered and follow the correct format. Check the plugin system in src/core/system.js.

// Correct plugin registration
const plugin = {
  statePlugins: {
    myPlugin: {
      selectors: {
        myData: () => (state) => state.get('myData')
      }
    }
  }
};

3. Performance Issues with Large Specifications

Problem: Swagger UI becomes slow with large OpenAPI specifications.

Solution: Use the docExpansion configuration option to control initial expansion, or implement pagination for operations.

const ui = SwaggerUI({
  url: "https://example.com/openapi.json",
  docExpansion: "none" // or "list" or "full"
});

4. Security Vulnerabilities

Problem: npm audit reports security vulnerabilities.

Solution: Keep dependencies updated and follow security best practices.

# Update dependencies
npm update

# Check for vulnerabilities
npm audit

# Fix vulnerabilities
npm audit fix

5. React Component Issues

Problem: swagger-ui-react not rendering correctly.

Solution: Ensure proper CSS import and correct props.

import React from 'react';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

function App() {
  return (
    <SwaggerUI
      url="https://petstore.swagger.io/v2/swagger.json"
      docExpansion="none"
    />
  );
}

6. Version Compatibility Issues

Problem: OpenAPI specification not compatible with Swagger UI version.

Solution: Check the compatibility table and use the appropriate version.

# Install specific version
npm install swagger-ui@5.0.0

Getting Help

• GitHub Issues: swagger-api/swagger-ui/issues
• Good First Issues: Look for issues labeled "Good first issue"
• Documentation: Swagger UI Documentation