Introducing Swama: A CLI Tool for Swagger/OpenAPI Interactions

APIs have become a critical part of software development. However, working with Swagger or OpenAPI specifications can sometimes feel like a manual and repetitive process. Wouldn't it be great if you could easily interact with these API specifications directly from your terminal?

That's where Swama comes in. Swama is a CLI tool built for developers who work with Swagger/OpenAPI specifications. It allows you to effortlessly explore, manipulate, and convert API definitions from the command line.

In this post, I’ll walk you through Swama’s features, how to install it, and how to use it to streamline your API development process.

What is Swama?

Swama is a command-line interface (CLI) tool designed to help developers interact with Swagger/OpenAPI definitions. It provides a simple way to list API endpoints, view detailed endpoint information, convert endpoints into curl or fetch commands, and more.

If you are tired of manually browsing through large API definitions or testing endpoints via Swagger UI, Swama is the perfect solution to boost your productivity.

Why Use Swama?

• No More Swagger UI: Browse and explore APIs directly from the command line.
• Endpoint Conversion: Quickly convert API endpoints into curl or fetch commands for easy testing.
• Filtering & Grouping: Filter and group endpoints by method, tags, or paths.
• Binaries for All Platforms: Pre-built binaries are available for Linux, macOS, and Windows.

Key Features

Here’s a rundown of some of Swama’s key features:

1. List API Endpoints

Swama allows you to list all available API endpoints in a Swagger or OpenAPI file. You can filter endpoints by HTTP method, tags, or specific paths using wildcard matching.

swama endpoints list --method GET --tag user

This command lists all GET endpoints tagged with user in the specified Swagger file.

2. View Endpoint Details

Want to know more about a specific endpoint? Swama allows you to view detailed information about any endpoint in the API specification.

swama endpoints view --endpoint /user --method GET

The above command will show detailed information about the /user endpoint, including its summary, request body, and response details.

3. Convert Endpoints to curl or fetch

Testing an API endpoint often involves writing curl or fetch commands. Swama simplifies this process by allowing you to instantly convert an API endpoint into one of these commands.

swama endpoints convert --file swagger.yaml --endpoint /api/users --method POST --type curl

This command converts the POST /api/users endpoint into a curl command that you can use in your terminal.

4. Explore Tags

APIs often use tags to categorize endpoints. Swama lets you list all tags in the API specification:

swama tags list --file swagger.yaml

With this command, you can easily see how the API is structured and what each tag represents.

5. List Servers

Many APIs are deployed across multiple servers (staging, production, etc.). Swama makes it easy to view all the servers listed in your API definition:

swama servers list --file swagger.yaml

This command gives you a quick overview of the environments your API is running in.

Installation

You can install Swama using the pre-built binaries available on the GitHub releases page. Follow these steps to get started:

1. Download the latest release for your platform (Linux, macOS, or Windows) from GitHub Releases.

2. Move the binary to your $PATH:

   • On Linux/macOS:

    sudo mv swama /usr/local/bin/
    sudo chmod +x /usr/local/bin/swama
   

• On Windows: Add the binary to your system’s PATH to run it globally.

Alternatively, you can build Swama from source:

git clone https://github.com/idsulik/swama
cd swama
go build -o swama

Once installed, run the following to verify the installation:

swama --help

Getting Started with Swama

Let’s walk through a few example commands that will get you up and running with Swama.

1. Listing All Endpoints

Want to list all the endpoints in your API definition? Use the list command:

swama endpoints list --file swagger.yaml

This will output all the API endpoints defined in the swagger.yaml file.

2. Viewing Endpoint Details

To view the details of a specific API endpoint, including methods, request bodies, and responses, use the view command:

swama endpoints view --file swagger.yaml --endpoint /api/users --method GET

3. Convert Endpoints to Testable Commands

One of Swama’s most powerful features is its ability to convert API endpoints into curl or fetch commands. For example, to convert an endpoint to a curl command:

swama endpoints convert --file swagger.yaml --endpoint /api/users --method POST --type curl

This command converts the POST /api/users endpoint into a curl command, making it super easy to test the API from the terminal.

Autocompletion for Faster Workflows

Swama supports autocompletion for various shells like Bash and Zsh. You can enable autocompletion for faster and more efficient workflows.

To generate the autocompletion script for your shell, run:

swama completion bash > /etc/bash_completion.d/swama

For Zsh:

swama completion zsh > ~/.zsh/completion/_swama

This allows you to quickly navigate through Swama commands and subcommands with autocompletion.

Final Thoughts

Swama brings the convenience of working with Swagger/OpenAPI definitions directly into your terminal. Whether you're listing endpoints, converting them to curl or fetch, or exploring tags and servers, Swama makes interacting with APIs seamless.

I built Swama to solve my own frustrations with manually browsing through Swagger files and converting API endpoints for testing. I hope it makes your development experience smoother as well.

By following these steps, you can simplify your interaction with API specifications, reduce manual work, and boost your productivity.