Если вы работаете с API, вы наверняка сталкивались с OpenAPI или Swagger для описания ваших API-спецификаций. Хотя эти инструменты облегчают процесс документирования, порой работать с ними через графические интерфейсы или ручной просмотр YAML-файлов бывает неудобно и утомительно.

Здесь на помощь приходит Swama — CLI-инструмент, позволяющий взаимодействовать с API-спецификациями напрямую из терминала. Он упрощает просмотр, фильтрацию и тестирование ваших API с использованием Swagger или OpenAPI.

Что такое Swama?

Swama — это командная утилита, созданная для взаимодействия со спецификациями Swagger/OpenAPI. Она позволяет:

• Листать и просматривать все доступные API-эндпоинты.

• Преобразовывать эндпоинты в команды curl или fetch для быстрого тестирования.

• Фильтровать эндпоинты по HTTP-методу, тегам и путям.

• Исследовать теги и серверы, указанные в спецификации API.

• {todo} Редактирование данных и экспорт в yaml/json

• {todo} Запус mock-сервера

• {todo} Команды для отправки запросов на api

Основные возможности

• Список API-эндпоинтов: Получите полный список всех доступных API-методов и их путей.

• Просмотр эндпоинтов: Подробно изучите каждый метод, его параметры, тело запроса и ответы.

• Конвертация в curl/fetch: Преобразуйте эндпоинты в команды curl или fetch для быстрого тестирования.

• Работа с тегами и серверами: Легко просматривайте и управляйте тегами и серверами в спецификации API.

Установка

Swama доступна как в виде предварительно собранных бинарных файлов, так и в виде исходного кода, который вы можете собрать самостоятельно.

Установка с помощью бинарных файлов

1. Перейдите на страницу релизов и скачайте последнюю версию для вашей операционной системы.

2. Добавьте бинарный файл в переменную окружения $PATH:

   • Linux/MacOS:

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

   • Windows: Добавьте файл в системный PATH для глобального доступа.

Сборка из исходников

Вы также можете собрать Swama вручную:

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

Пример использования

После установки Swama можно начинать взаимодействовать с вашими Swagger/OpenAPI файлами через командную строку.

Список эндпоинтов

Для того чтобы получить полный список всех эндпоинтов, используйте следующую команду:

swama endpoints list --file swagger.yaml

Вы также можете фильтровать эндпоинты по методу, тегам или конкретным путям:

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

Просмотр информации об эндпоинте

Чтобы получить подробную информацию о конкретном эндпоинте, включая HTTP-метод, тело запроса и возможные ответы, используйте команду:

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

Конвертация эндпоинта в команду curl или fetch

Одной из ключевых функций Swama является возможность конвертации эндпоинтов в команды curl или fetch для тестирования:

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

Общая информация о Swagger/OpenAPI файле

Команда info позволяет быстро получить основную информацию о вашем Swagger/OpenAPI файле, такую как версия, заголовок и описание API.:

swama info view

Список серверов

Команда servers list выводит список всех серверов, определенных в Swagger/OpenAPI файле, включая их URL и описание. Это может быть полезно, если у вас есть несколько окружений, таких как тестовое, staging или production:

swama servers list

Список тегов

Теги в API используются для группировки эндпоинтов. Команда tags list выводит все теги, указанные в спецификации API:

swama tags list

Автодополнение

Swama поддерживает автодополнение для командной строки, что позволяет ускорить работу с инструментом. Чтобы включить автодополнение, выполните следующие команды:

• Bash:

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

• Zsh:

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

Заключение

Swama значительно упрощает работу с API-спецификациями. Теперь, вместо того чтобы вручную искать нужные эндпоинты в Swagger UI или постоянно писать команды curl, вы можете сделать всё это прямо из вашего терминала.

p.s. напишите в комментариях свои идеи, как можно улучшить инструмент, чтобы он стал еще удобнее и полезнее. Спасибо!