How To Install Swagger on Ubuntu 24.04 LTS

Swagger has become an essential tool for API developers seeking to document, test, and visualize their REST APIs with minimal effort. With the recent release of Ubuntu 24.04 LTS (Noble Numbat), many developers are looking to set up their API documentation environment on this stable, long-term support platform. This comprehensive guide walks you through multiple methods to install and configure Swagger on Ubuntu 24.04, ensuring you have a robust setup for your API development needs.

Introduction

Swagger, now formally known as the OpenAPI Specification, provides a standardized approach to describing REST APIs. It allows developers to document APIs in a way that’s both human and machine-readable, facilitating better understanding and interaction with web services. The structured format of Swagger enables automatic generation of interactive documentation, client libraries, and server stubs, making API development more efficient and consistent.

Ubuntu 24.04 LTS (Noble Numbat) offers an ideal platform for API development due to its long-term support, stability, and robust package management. As the latest LTS release, it provides a secure foundation for deploying production-ready API documentation systems that will receive updates for years to come.

By the end of this guide, you’ll have a fully functional Swagger environment on your Ubuntu system, allowing you to create, edit, and share interactive API documentation with your team or end-users.

Prerequisites and System Requirements

Before proceeding with the installation, ensure your system meets the following requirements to avoid compatibility issues during setup.

Minimum System Specifications

Your Ubuntu 24.04 system should have at least:

• 2GB RAM (4GB recommended for smoother performance)
• Dual-core processor
• 5GB free disk space
• Internet connection for downloading packages

Ensuring Your System is Up-to-Date

First, update your Ubuntu system to ensure all packages are current:

sudo apt update
sudo apt upgrade -y

This ensures compatibility and security for your Swagger installation. The update process might take a few minutes depending on your internet speed and the number of packages that need updating.

Development Tools Installation

Install these essential packages to support your Swagger environment:

sudo apt install curl git build-essential -y

These tools provide the foundation for downloading, building, and managing your Swagger components and dependencies.

Understanding Swagger Components and Architecture

Before installation, let’s clarify what makes up the Swagger ecosystem to help you decide which components you need.

Swagger Ecosystem Overview

Swagger consists of several key tools that work together:

• Swagger Editor: A browser-based editor where you can write OpenAPI specifications with real-time visualization and validation feedback
• Swagger UI: A collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from an OpenAPI specification
• Swagger Codegen: Generates client libraries, server stubs, and API documentation from your OpenAPI specs

OpenAPI Specification Basics

The OpenAPI Specification (formerly Swagger Specification) forms the foundation of the Swagger ecosystem. It’s a format that allows you to describe your API in either YAML or JSON format. The specification includes:

• API endpoints and operations
• Input and output parameters
• Authentication methods
• Contact information and license

How Components Work Together

In a typical workflow:

1. You create or edit your API specification in Swagger Editor
2. The specification validates in real-time as you work
3. Swagger UI renders interactive documentation from your specification
4. Developers or end-users interact with your API through this documentation
5. Optionally, Swagger Codegen generates client libraries for various languages

This integrated approach ensures consistency between your API implementation and documentation.

Installation Method 1: Using Node.js and npm

The Node.js-based installation is popular for developers already working in JavaScript environments and offers simplicity and flexibility.

Setting Up Node.js Environment

First, install Node.js and npm on your Ubuntu 24.04 system:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Verify the installation with:

node -v
npm -v

Both commands should return version numbers, confirming successful installation.

Installing Swagger Editor via npm

With Node.js in place, install the HTTP server package and clone the Swagger Editor repository:

npm install -g http-server
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor

This creates a local copy of the Swagger Editor that you can run and customize according to your needs.

Verifying the Installation

Start the Swagger Editor with:

http-server -p 8080

Now open your browser and navigate to http://127.0.0.1:8080 to access the Swagger Editor interface. You should see the editor loaded with a sample pet store API definition that you can modify for your projects.

Running Your First Swagger Project

To start a new API definition:

1. Clear the example content
2. Begin defining your API endpoints, parameters, and responses
3. Save your work by exporting to JSON or YAML format
4. The editor provides real-time validation and visualization as you work

This method gives you full control over the editor and allows for offline usage.

Installation Method 2: Using Docker

Docker provides an isolated, consistent environment for running Swagger components without worrying about dependencies or system configuration conflicts.

Docker Setup on Ubuntu 24.04

If you don’t have Docker installed yet:

sudo apt update
sudo apt install docker.io docker-compose -y
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Log out and back in for the group changes to take effect, or run newgrp docker to update your current session.

Pulling and Running Swagger Docker Images

For Swagger Editor:

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

For Swagger UI:

docker pull swaggerapi/swagger-ui
docker run -d -p 8080:8080 swaggerapi/swagger-ui

These commands download the official Swagger images and start containers accessible on ports 80 (Editor) and 8080 (UI).

Container Configuration and Management

To customize your Swagger container, you can pass environment variables:

docker run -d -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

This mounts your local /bar directory to /foo within the container and uses a specific swagger.json file for the UI.

Working with Existing Swagger Files

If you already have a Swagger definition file, you can mount it to the container:

mkdir -p ~/swagger-files
cp your-swagger.json ~/swagger-files/swagger.json
docker run -d -p 80:8080 -v $PWD/swagger-files:/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

This makes your existing definition available in the editor for further modifications.

Docker Compose for Multi-Container Setup

For a complete environment with both Editor and UI, create a docker-compose.yml file:

version: '3'
services:
  swagger-editor:
    image: swaggerapi/swagger-editor
    ports:
      - "80:8080"
  swagger-ui:
    image: swaggerapi/swagger-ui
    ports:
      - "8080:8080"
    environment:
      - SWAGGER_JSON=/tmp/swagger.json
    volumes:
      - ./swagger-files:/tmp

Then start the services with:

docker-compose up -d

This approach simplifies managing the different Swagger components as a unified system.

Installation Method 3: Using Snap Package

The Snap package system offers a convenient way to install and update applications on Ubuntu with automatic updates and dependency management.

Understanding Snap Packages

Snap packages are containerized software packages designed for easy installation and updates across Linux distributions. They include all necessary dependencies, making installation straightforward.

Installing go-swagger via Snap

Ubuntu 24.04 comes with Snap pre-installed. To install the go-swagger package:

sudo snap install go-swagger

This single command installs the go-swagger implementation, a Golang-based Swagger toolset that provides command-line utilities for working with OpenAPI specifications.

Post-Installation Configuration

After installation, the swagger command becomes available in your system path. Verify with:

swagger version

No additional configuration is typically needed as the Snap package includes all required dependencies.

Advantages and Limitations of Snap Installation

Advantages:

• Automatic background updates
• Simplified installation process
• Consistent behavior across Linux distributions

Limitations:

• May use more disk space than traditional packages
• Some performance overhead compared to native packages
• Limited customization options compared to source installations

Post-Installation Setup and Basic Usage

Once you’ve installed Swagger using any of the methods above, you’ll want to configure it for your specific needs.

First-Time Configuration Steps

For the best experience, configure your editor preferences:

1. If using Swagger Editor, click on the “Edit” menu
2. Select “Preferences”
3. Adjust settings like indentation, line wrapping, and theme
4. Save your preferences for future sessions

Creating Your First API Documentation

Start documenting your API:

1. Begin with the OpenAPI version declaration and info section
2. Define servers, paths, and components
3. Add descriptions, examples, and response codes for each endpoint
4. Use the validation features to ensure compliance with the OpenAPI specification

A basic OpenAPI 3.0 definition looks like:

openapi: 3.0.0
info:
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Hello world endpoint
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

Swagger Editor Interface Overview

The Swagger Editor interface consists of:

• Left panel: YAML/JSON editor with syntax highlighting
• Right panel: Live documentation preview
• Top menu: File operations, edit functions, and generation options
• Bottom panel: Validation errors and warnings

Familiarize yourself with these areas to maximize productivity.

Saving and Exporting Your Work

To preserve your API documentation:

1. Use File > Save as YAML or File > Save as JSON
2. Consider version control with Git for tracking changes
3. Export to various formats like HTML, PDF, or markdown for sharing

Regular saving prevents work loss and creates checkpoints in your API design process.

Advanced Configuration Options

After mastering the basics, explore these advanced options to enhance your Swagger implementation.

Customizing Swagger UI

Personalize the documentation interface:

1. Modify the CSS to match your brand colors
2. Add your organization’s logo
3. Customize the layout and display options
4. Adjust the default expanded/collapsed sections

For Docker installations, you can use environment variables to control these aspects:

docker run -p 8080:8080 -e SWAGGER_UI_ALWAYS_DISPLAY_OPERATION_ID="true" swaggerapi/swagger-ui

Security Considerations

Protect your API documentation:

1. Configure authentication for access control
2. Set up HTTPS for encrypted connections
3. Consider restricting network access to sensitive APIs
4. Implement CORS policies to control domain access

For public-facing documentation, always implement suitable security measures.

Performance Optimization

Improve loading speeds and responsiveness:

1. Optimize your OpenAPI definition file size
2. Use caching headers when serving documentation
3. Consider using a CDN for public documentation
4. Split large specifications into referenced components

These optimizations become increasingly important as your API grows in complexity.

Integrating Swagger with Existing Projects

Swagger shines when integrated with your existing application codebase, providing up-to-date documentation that evolves with your API.

Adding Swagger to Node.js Applications

For Express.js applications:

npm install swagger-jsdoc swagger-ui-express --save

Then in your application:

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

This setup automatically generates documentation from JSDoc comments in your route files.

Python and Django Integration

For Django REST framework:

pip install drf-yasg

Add to your settings.py:

INSTALLED_APPS = [
    # ...
    'drf_yasg',
]

Configure in urls.py:

from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
   openapi.Info(
      title="My API",
      default_version='v1',
   ),
   public=True,
)

urlpatterns = [
   # ...
   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0)),
]

This integration automatically builds Swagger documentation from your Django REST views.

Java/Spring Boot Integration

Add to your pom.xml:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

Annotate your controllers and models, then access Swagger UI at /swagger-ui.html.

Troubleshooting Common Issues

Even with careful installation, you might encounter some issues. Here are solutions to common problems.

Installation Problems and Solutions

Problem: Node.js or npm command not found
Solution: Verify installation with which nodejs and which npm. Reinstall if necessary.

Problem: Permission errors during npm installation
Solution: Use sudo npm install -g http-server or configure npm to use a different directory.

Problem: Docker container not starting
Solution: Check for port conflicts with sudo lsof -i:80 or sudo lsof -i:8080 and use different ports if needed.

Runtime Errors

Problem: Swagger Editor blank page
Solution: Check browser console for errors, ensure no content-security-policy issues are blocking scripts.

Problem: CORS errors when accessing API from Swagger UI
Solution: Configure your API server to allow cross-origin requests from your Swagger UI domain.

Validation and Parsing Errors

Problem: OpenAPI validation failures
Solution: Use the editor’s validation feedback to identify and fix specification issues. Check indentation in YAML files.

Problem: References ($ref) not resolving
Solution: Ensure paths are correct and files are accessible. For Docker installs, check volume mounts.

Keeping Swagger Updated on Ubuntu 24.04

Maintaining an up-to-date Swagger installation ensures you have the latest features and security fixes.

Update Procedures by Installation Method

For npm installations:

npm update -g http-server
cd swagger-editor
git pull

For Docker installations:

docker pull swaggerapi/swagger-editor
docker pull swaggerapi/swagger-ui
# Restart your containers after pulling

For Snap package installations:

sudo snap refresh go-swagger

Snap packages typically update automatically, but this command forces an immediate update.

Congratulations! You have successfully installed Swagger. Thanks for using this tutorial for installing Swagger on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Swagger website.