Checker API Example

Guide: Self-Hosting Swagger UI for API Documentation

This guide provides step-by-step instructions on how to set up Swagger UI on your own web server to host your API documentation.

Prerequisites

Steps to Self-Host Swagger UI

Step 1: Download Swagger UI

  1. Go to the Swagger UI GitHub Releases page: https://github.com/swagger-api/swagger-ui/releases
  2. Download the latest stable release: Look for a release like "Swagger UI 5.x.x" and find the swagger-ui-5.x.x.zip (or similar) file under the "Assets" section.
  3. Extract the contents: Unzip the downloaded file. Inside, you'll find a dist folder. This folder contains all the necessary HTML, CSS, and JavaScript files to run Swagger UI.

Step 2: Prepare Your OpenAPI Specification

  1. Place your openapi.yaml file: Decide where you want to store your openapi.yaml file on your server. A common practice is to place it directly in the root of your Swagger UI deployment (e.g., your-docs-folder/openapi.yaml) or in a subfolder like specs/.

Example Placement: If your web server serves files from /var/www/html/api-docs/, then you might place your openapi.yaml directly into /var/www/html/api-docs/openapi.yaml or in /var/www/html/api-docs/specs/openapi.yaml.

Step 3: Deploy Swagger UI Files to Your Web Server

  1. Choose a directory on your web server: Create a new directory where you want to host your API documentation.
    • Apache example: /var/www/html/api-docs/ or /var/www/your-domain/public_html/api-docs/.
    • Nginx example: /usr/share/nginx/html/api-docs/.
  2. Copy dist contents: Copy all the contents of the dist folder (from your Swagger UI download) into the directory you created on your web server.

    So, if your downloaded dist folder contained index.html, swagger-ui.css, swagger-ui-bundle.js, etc., these files should now be directly inside your web server's api-docs/ directory.

Step 4: Configure Swagger UI to Load Your Spec (Important for newer versions)

In modern Swagger UI versions (5.x.x+), the configuration is in swagger-initializer.js.

  1. Open swagger-initializer.js: Navigate to your Swagger UI deployment directory (e.g., api-docs/) on your server and open the swagger-initializer.js file in a text editor.
  2. Locate the SwaggerUIBundle configuration: Find the window.onload function containing the SwaggerUIBundle initialization. It will look similar to this: 
    window.onload = function() {
  // Begin Swagger UI call region
  const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json", // This is the line to change!
    dom_id: '#swagger-ui',
    // ... other configuration options
  });
  // End Swagger UI call region
};
  3. Change the url parameter:
    • If openapi.yaml is in the same directory: Change url: "https://petstore.swagger.io/v2/swagger.json" to: 
      url: "./openapi.yaml",
    • If openapi.yaml is in a subfolder (e.g., specs/): Change url: "https://petstore.swagger.io/v2/swagger.json" to: 
      url: "./specs/openapi.yaml",
    • If your OpenAPI spec is served from a different URL (e.g., your actual API endpoint serves it): Provide the full absolute URL: 
      url: "https://your-api.com/v1/openapi.json", // Example absolute URL
  4. Save swagger-initializer.js: Save the changes to the file.

Step 5: Configure Your Web Server (Crucial for Public Access & Security)

This step makes your documentation accessible and secure. You'll need root/administrator access to your server.

For Apache (example):

  1. Create a Virtual Host (recommended): Create a new Apache configuration file (e.g., /etc/apache2/sites-available/your-docs.conf). 
    <VirtualHost *:80>
    ServerName docs.your-domain.com # Change to your domain/subdomain
    DocumentRoot /var/www/html/api-docs # Path where you copied Swagger UI files

    <Directory /var/www/html/api-docs>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/api-docs_error.log
    CustomLog ${APACHE_LOG_DIR}/api-docs_access.log combined
</VirtualHost>
  2. Enable the site (on Debian/Ubuntu): 
    sudo a2ensite your-docs.conf
  3. Restart Apache: 
    sudo systemctl restart apache2
    (or sudo service apache2 restart)

For Nginx (example):

  1. Create a Server Block: Create a new Nginx configuration file (e.g., /etc/nginx/sites-available/your-docs.conf). 
    server {
    listen 80;
    server_name docs.your-domain.com; # Change to your domain/subdomain
    root /usr/share/nginx/html/api-docs; # Path where you copied Swagger UI files
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
  2. Create a symlink (if applicable): 
    sudo ln -s /etc/nginx/sites-available/your-docs.conf /etc/nginx/sites-enabled/
  3. Test Nginx config: 
    sudo nginx -t
  4. Restart Nginx: 
    sudo systemctl restart nginx
    (or sudo service nginx restart)

Important: Implement HTTPS for Public Access

NEVER expose public-facing documentation without HTTPS.

  1. Get an SSL Certificate: The easiest and free way is using Let's Encrypt with certbot.
    • Install certbot for your web server and OS (e.g., sudo apt install certbot python3-certbot-apache or sudo apt install certbot python3-certbot-nginx).
    • Run sudo certbot --apache or sudo certbot --nginx and follow the prompts. It will handle certificate generation and web server configuration automatically, including redirects from HTTP to HTTPS.
  2. Configure DNS: Ensure your domain/subdomain (e.g., docs.your-domain.com) points to the public IP address of your server where Swagger UI is hosted.

Step 6: Access Your Documentation

  1. Open your web browser and navigate to the URL where you've deployed Swagger UI (e.g., https://docs.your-domain.com/).

You should now see your interactive API documentation rendered by Swagger UI, loading your openapi.yaml file!

Workflow Tips