CLI tool for working with Swagger

If you work with APIs, you've probably encountered OpenAPI or Swagger to describe your API specifications. While these tools make the documentation process easier, they can sometimes be awkward and tedious to work with via graphical interfaces or manually browsing YAML files.

This is where it comes to the rescue Swama — A CLI tool that allows you to interact with API specifications directly from the terminal. It makes it easy to view, filter, and test your APIs using Swagger or OpenAPI.

What is Swama?

Swama — is a command line utility designed to interact with Swagger/OpenAPI specifications. It allows you to:

• Scroll and view all available API endpoints.

• Convert endpoints to commands curl or fetch for quick testing.

• Filter endpoints by HTTP method, tags and paths.

• Explore the tags and servers specified in the API specification.

• {todo} Editing data and exporting to yaml/json

• {todo} Starting a mock server

• {todo} Commands for sending requests to api

Main features

• List of API endpoints: Get a complete list of all available API methods and their paths.

• View endpoints: Explore each method in detail, its parameters, request body and responses.

• Convert to curl/fetch: Convert endpoints to commands curl or fetch for quick testing.

• Working with tags and servers: Easily view and manage tags and servers in the API specification.

Installation

Swama is available both as pre-built binaries and as source code that you can build yourself.

Installation using binaries

1. Go to releases page and download the latest version for your operating system.

2. Add the binary to the environment variable $PATH:

   • Linux/MacOS:

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

   • Windows: Add the file to the system PATH for global access.

Build from sources

You can also build Swama manually:

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

Example of use

Once Swama is installed, you can start interacting with your Swagger/OpenAPI files via the command line.

List of endpoints

To get a complete list of all endpoints, use the following command:

swama endpoints list --file swagger.yaml

You can also filter endpoints by method, tags, or specific paths:

swama endpoints list --method GET --tag user
# если не указан "--flag", то будет сделана попытка найти файл в текущей директории

Viewing endpoint information

To get detailed information about a specific endpoint, including the HTTP method, request body, and possible responses, use the command:

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

Converting an endpoint to a curl or fetch command

One of the key features of Swama is the ability to convert endpoints into commands. curl or fetch for testing:

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

General information about Swagger/OpenAPI file

The info command allows you to quickly get basic information about your Swagger/OpenAPI file, such as the version, title, and API description:

swama info view

List of servers

Team servers list lists all servers defined in a Swagger/OpenAPI file, including their URLs and descriptions. This can be useful if you have multiple environments, such as testing, staging, or production:

swama servers list

List of tags

Tags in the API are used to group endpoints. Command tags list outputs all tags specified in the API specification:

swama tags list

Autocompletion

Swama supports command line autocompletion, which allows you to work faster with the tool. To enable autocompletion, run the following commands:

Conclusion

Swama makes working with API specifications much easier. Now, instead of manually searching for the necessary endpoints in Swagger UI or constantly writing commands curlyou can do all this right from your terminal.

ps write in the comments your ideas on how to improve the tool to make it even more convenient and useful. Thank you!