Swama: CLI-инструмент для работы с Swagger/OpenAPI

Если вы работаете с 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 доступна как в виде предварительно собранных бинарных файлов, так и в виде исходного кода, который вы можете собрать самостоятельно.

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

Перейдите на страницу релизов и скачайте последнюю версию для вашей операционной системы.
Добавьте бинарный файл в переменную окружения $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. напишите в комментариях свои идеи, как можно улучшить инструмент, чтобы он стал еще удобнее и полезнее. Спасибо!

ссылка на оригинал статьи https://habr.com/ru/articles/843824/