How To Install Swagger on Manjaro

Swagger has become an essential tool for developers working with APIs, offering a standardized way to document, visualize, and test RESTful web services. For Manjaro Linux users, installing and configuring Swagger might seem challenging at first, but this comprehensive guide will walk you through multiple installation methods to suit your specific needs. Whether you’re a backend developer looking to document your APIs or a frontend developer needing to interact with existing APIs, this article will help you set up Swagger on your Manjaro system efficiently.

Table of Contents

Introduction

Swagger, now officially known as the OpenAPI Specification, is an open-source framework that helps developers design, build, document, and consume RESTful web services. It allows you to describe your API structure in a way that’s both human and machine-readable, creating interactive documentation that makes understanding and testing APIs straightforward.

Manjaro Linux, a popular Arch-based distribution, offers users the stability and user-friendliness of traditional distributions while providing access to cutting-edge software through its rolling release model. This combination makes it an excellent platform for developers, including those working with API documentation tools like Swagger.

In this guide, we’ll explore various methods to install Swagger on Manjaro, covering everything from package management solutions to containerized deployments. By the end, you’ll have a functional Swagger environment tailored to your specific development needs.

Understanding Swagger and Its Components

Before diving into installation procedures, it’s important to understand what constitutes the Swagger ecosystem and how its various components work together.

Swagger, or the OpenAPI Specification, is fundamentally a format for describing RESTful APIs. This specification has evolved over the years, with OpenAPI 3.0 being the current standard that many developers use. The ecosystem consists of several core tools:

Swagger UI: A collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from an OpenAPI specification. This interactive documentation allows users to try out API calls directly from the browser.

Swagger Editor: An online editor where you can write OpenAPI specifications in YAML or JSON format with real-time validation and visualization.

Swagger Codegen: A tool that generates server stubs and client libraries in various programming languages based on an OpenAPI specification.

Swagger Inspector: An API testing tool that lets you validate your APIs against OpenAPI definitions.

The benefits of implementing Swagger in your development workflow include:

Standardized documentation that stays synchronized with your code
Interactive API exploration capabilities for developers and users
Automatic validation of API requests and responses
Enhanced collaboration between frontend and backend teams
Simplified API testing and debugging
Code generation capabilities to speed up development

With a clear understanding of these components, let’s proceed to prepare your Manjaro system for Swagger installation.

Prerequisites for Installing Swagger on Manjaro

Before installing Swagger on your Manjaro Linux system, ensure you meet the following requirements:

A Manjaro Linux installation with internet access
Basic knowledge of terminal commands and Linux file structure
Sufficient disk space (at least 500MB free)
User account with sudo privileges
Updated system packages

To update your Manjaro system, open a terminal and run:

sudo pacman -Syu

This command synchronizes your package databases and updates all installed packages to their latest versions. It’s crucial to start with an updated system to avoid dependency issues during installation.

Additionally, it’s a good practice to back up any important configuration files before proceeding with new software installations. While Swagger installation shouldn’t affect system stability, following proper backup procedures ensures you can recover if something goes wrong.

With these prerequisites in place, let’s explore the various methods to install Swagger on Manjaro.

Method 1: Installing Swagger UI via Snap Package

Snap packages provide a convenient way to install software across different Linux distributions with all dependencies included. Manjaro supports snaps, making this an excellent method for installing Swagger tools.

Installing the Snap Package Manager

First, install the snap daemon and related components:

sudo pacman -S snapd libpamac-snap-plugin

Once installed, enable and start the snapd service:

sudo systemctl enable --now snapd.socket

For complete snap functionality, especially with classic snaps (which have broader system access), create a symbolic link:

sudo ln -s /var/lib/snapd/snap /snap

After these steps, you’ll need to log out and log back in or restart your system to ensure the snap paths are correctly updated.

Installing Swagger UI via Snap

With snapd properly configured, you can now install Swagger UI:

sudo snap install swagger-ui

For the AWS API Gateway specific version, you can use:

sudo snap install apig-swagger-ui

Verifying the Installation

To verify that Swagger UI is correctly installed, check the snap list:

snap list

The output should include swagger-ui or your specific Swagger package. Depending on the specific snap package, you might access Swagger UI through a web browser at a local address like http://localhost:8080 or through a specific command.

The snap installation method offers several advantages:

Automatic updates
Isolation from system libraries
Easy installation and removal
Consistent behavior across Linux distributions

However, it also has some limitations:

Increased disk usage due to bundled dependencies
Potential performance overhead
Some snaps have limited system integration

Method 2: Manual Installation of Swagger UI

For users who prefer more control over their installation or need specific configurations, manually installing Swagger UI from source is a viable option.

Downloading Swagger UI

First, install git if you don’t have it already:

sudo pacman -S git

Next, clone the Swagger UI repository:

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui/

Setting Up Node.js Environment

Swagger UI requires Node.js and npm for building and running. Install them with:

sudo pacman -S nodejs npm

Building Swagger UI

Once Node.js and npm are installed, build the Swagger UI package:

npm install
npm run build

This process might take several minutes as it downloads dependencies and compiles the necessary files.

Configuring and Running Swagger UI

After building, you can start the Swagger UI development server:

npm run start

By default, this makes Swagger UI available at http://localhost:3200 or http://localhost:3002 depending on your version.

For a more permanent setup, you can copy the contents of the dist directory to your web server’s document root:

sudo cp -r dist/* /var/www/html/swagger/

Then, customize the swagger-initializer.js file to point to your API specification:

sudo nano /var/www/html/swagger/swagger-initializer.js

Replace the default URL “https://petstore.swagger.io/v2/swagger.json” with the path to your OpenAPI specification file.

The manual installation method gives you full control over the installation process and allows for extensive customization, but requires more technical knowledge and manual maintenance.

Method 3: Docker Installation for Swagger UI

Docker provides an excellent way to deploy Swagger UI without worrying about dependencies or system configuration. This method is particularly useful for development environments or when you need to run multiple instances with different configurations.

Installing Docker on Manjaro

First, install Docker:

sudo pacman -S docker

Start and enable the Docker service:

sudo systemctl start docker.service
sudo systemctl enable docker.service

To run Docker commands without sudo, add your user to the docker group:

sudo usermod -aG docker $USER

Log out and back in for this change to take effect.

Running Swagger UI Container

Pull the official Swagger UI Docker image:

docker pull swaggerapi/swagger-ui

Run the container with basic configuration:

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

This command makes Swagger UI available at http://localhost:8080.

Advanced Docker Configuration

To use your own OpenAPI specification, mount it as a volume:

docker run -p 8080:8080 -e SWAGGER_JSON=/foo/swagger.json -v /path/to/your/spec:/foo swaggerapi/swagger-ui

Alternatively, specify a URL to your specification:

docker run -p 8080:8080 -e SWAGGER_JSON_URL=https://example.com/swagger.json swaggerapi/swagger-ui

You can also change the base URL path:

docker run -p 8080:8080 -e BASE_URL=/swagger swaggerapi/swagger-ui

With this configuration, Swagger UI will be accessible at http://localhost:8080/swagger instead of the root path.

Docker provides excellent isolation and reproducibility, making it easy to create consistent environments for development, testing, and production. It’s particularly valuable when you need to manage multiple API specifications or versions.

Method 4: Installing AUR Package for Swagger UI

The Arch User Repository (AUR) contains community-maintained packages for Arch-based distributions like Manjaro. This method leverages Manjaro’s package management system for a more integrated installation.

Installing an AUR Helper

While you can manually build and install AUR packages, using an AUR helper simplifies the process. Yay is a popular choice:

sudo pacman -S yay

Finding and Installing Swagger UI from AUR

Search for Swagger-related packages:

yay -Ss swagger

Install the appropriate package, for example:

yay -S swagger-ui-git

The installation process will download the source code, compile it, and install it according to the package’s build instructions.

Configuring AUR-installed Swagger UI

AUR packages typically follow Arch Linux conventions for file locations. Configuration files might be located in /etc/swagger-ui/, while web assets could be in /usr/share/swagger-ui/.

To customize your installation, locate and edit the configuration files:

sudo nano /etc/swagger-ui/config.json

Some AUR packages may include systemd service files, which you can enable with:

sudo systemctl enable --now swagger-ui.service

Using AUR packages integrates well with Manjaro’s package management system, allowing easier updates and dependencies handling through standard system tools.

Method 5: Using Swagger with Go Projects

For Go developers, the swag tool offers a convenient way to generate Swagger/OpenAPI documentation directly from Go code annotations.

Installing Go and Swag

First, install Go if you haven’t already:

sudo pacman -S go

Then install the swag command-line tool:

go install github.com/swaggo/swag/cmd/swag@latest

Ensure that $GOPATH/bin is in your PATH:

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

Setting Up a Go Project with Swagger Annotations

Create a new Go project or navigate to an existing one:

mkdir -p ~/projects/go-api-example
cd ~/projects/go-api-example
go mod init example.com/go-api

Add Swagger annotations to your Go code. Here’s a simple example:

// main.go

package main

import (
    "net/http"
    
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

// @title API Example
// @version 1.0
// @description This is a sample server.
// @host localhost:8080
// @BasePath /api/v1
func main() {
    r := gin.Default()
    
    // Use swagger
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    // Sample API endpoint
    r.GET("/api/v1/hello", HelloHandler)
    
    r.Run(":8080")
}

// HelloHandler godoc
// @Summary Say hello
// @Description Get a hello message
// @Produce json
// @Success 200 {object} map[string]string
// @Router /hello [get]
func HelloHandler(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"message": "Hello, world!"})
}

Generating Swagger Documentation

Install the necessary dependencies:

go get github.com/gin-gonic/gin
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

Generate the Swagger documentation:

swag init

This command creates a docs directory containing your API specification in both JSON and YAML formats.

Running Your Go Application with Swagger UI

Build and run your application:

go build -o api-server
./api-server

Access the Swagger UI by navigating to http://localhost:8080/swagger/index.html in your browser.

This method integrates Swagger directly into your Go development workflow, keeping documentation synchronized with your code and reducing maintenance overhead.

Configuring Your Swagger Installation

Regardless of the installation method you chose, proper configuration is essential for a useful Swagger setup.

Basic Configuration Options

The primary configuration file for Swagger UI is typically named swagger-initializer.js or similar. Key options include:

Setting the URL to your OpenAPI specification
Configuring the UI theme and layout
Enabling or disabling specific features

For example, to modify the specification URL:

window.onload = function() {
  window.ui = SwaggerUIBundle({
    url: "https://your-api-server.com/api/swagger.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });
};

Customizing the Appearance

You can customize the Swagger UI appearance by overriding CSS styles or using themes:

/* custom.css */
.swagger-ui .topbar {
  background-color: #222;
}

.swagger-ui .info .title {
  color: #47a3da;
}

Link your custom CSS in the HTML file that loads Swagger UI.

Setting Up Authentication

For APIs that require authentication, configure security definitions in your OpenAPI specification:

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Then apply this security scheme to your API endpoints.

Optimizing Performance

For better performance, consider:

Minifying your OpenAPI specification
Using a CDN for Swagger UI assets in production
Implementing browser caching for static assets
Splitting large API specifications into multiple files using references

Proper configuration ensures your Swagger installation is not only functional but also optimized for your specific use case.

Creating Your First API Documentation

With Swagger installed and configured on your Manjaro system, you’re ready to create your first API documentation.

Basic Structure of OpenAPI Specification

An OpenAPI specification typically includes:

General information about the API
Server URLs
Available paths (endpoints)
Operations (HTTP methods) for each path
Parameters for each operation
Response schemas
Component definitions (schemas, security schemes, etc.)

Here’s a simple example:

openapi: 3.0.0
info:
  title: Sample API
  description: A sample API to demonstrate OpenAPI
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://dev-api.example.com/v1
    description: Development server
paths:
  /users:
    get:
      summary: Returns a list of users
      description: Optional extended description
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Testing Your Documentation

After creating your specification, load it into Swagger UI to verify it renders correctly and all endpoints are documented properly. Use the “Try it out” feature to test API calls directly from the documentation.

To test API responses, ensure your API server is running and accessible from the browser where Swagger UI is loaded.

Validating Your OpenAPI Document

Use tools like the Swagger Editor or OpenAPI validators to check your specification for errors:

npm install -g @apidevtools/swagger-cli
swagger-cli validate path/to/your/openapi.yaml

A well-structured API documentation is invaluable for both internal development teams and external API consumers, so invest time in making it comprehensive and accurate.

Troubleshooting Common Issues

When working with Swagger on Manjaro, you might encounter some common issues. Here’s how to diagnose and fix them:

Permission Errors

If you encounter permission issues:

sudo chown -R $USER:$USER ~/.npm
sudo chmod -R 755 /usr/local/lib/node_modules

For Docker-related permission issues:

sudo chmod 666 /var/run/docker.sock

Network and Connection Problems

If Swagger UI can’t access your API:

Verify your API server is running
Check for CORS issues in your browser’s developer console
Ensure firewalls aren’t blocking connections

For CORS issues, configure your API server to allow requests from Swagger UI’s origin:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Origin, Content-Type, Accept, Authorization

Browser Caching Issues

If changes to your API aren’t reflecting in Swagger UI:

Clear your browser cache
Use private/incognito mode
Add a cache-busting query parameter to your specification URL

Configuration Syntax Errors

For YAML syntax errors:

npm install -g js-yaml
js-yaml path/to/your/openapi.yaml > /dev/null

This command will output any syntax errors in your YAML file.

Missing Dependencies

If you’re getting errors about missing dependencies when building Swagger UI:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Don’t hesitate to consult the official Swagger documentation or community forums like Stack Overflow when facing persistent issues.

Advanced Usage Scenarios

Once you’ve mastered the basics, explore these advanced Swagger features and integration options:

Integrating with CI/CD Pipelines

Automate API documentation updates in your CI/CD pipeline:

# Example GitLab CI configuration
stages:
  - build
  - deploy

build-docs:
  stage: build
  script:
    - swag init
    - cp -r docs/swagger public/
  artifacts:
    paths:
      - public/swagger

deploy-docs:
  stage: deploy
  script:
    - rsync -avz public/swagger/ user@server:/var/www/swagger-ui/

Version Control for API Documentation

Keep your API documentation versioned alongside your code:

Include OpenAPI specifications in your git repository
Use tags or branches for different API versions
Consider using semantic versioning for your API

Multiple Environment Configurations

Configure Swagger UI for different environments:

const environments = {
  development: "https://dev-api.example.com/v1/swagger.json",
  staging: "https://staging-api.example.com/v1/swagger.json",
  production: "https://api.example.com/v1/swagger.json"
};

// Detect environment or provide UI to select
const currentEnv = detectEnvironment();
const specUrl = environments[currentEnv];

window.onload = function() {
  window.ui = SwaggerUIBundle({
    url: specUrl,
    // other configuration...
  });
};

Code Generation from OpenAPI Specifications

Generate client libraries for your API:

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate a TypeScript client
openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

These advanced techniques can significantly enhance your API development workflow and improve collaboration between teams.

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

VPS Manage Service Offer

If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!